Skip to content

Outbound (Reach Out) ​

Have an agent reach out to someone — place a call, or open a conversation on SMS, WhatsApp or email.

OperationEndpointScope
Start an outbound conversationPOST /api/v1/outboundconversations:write
bash
curl -X POST "https://<your-workspace>-api.perfox.ai/api/v1/outbound" \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "01a0…",
    "channel": "phone",
    "to": "+919876543210"
  }'
FieldValues
agent_idA published agent that has a Trigger for this channel
channelphone, sms, whatsapp or email
toPhone number or email address to reach
opening_messageOptional, up to 2,000 characters — on SMS, WhatsApp and email it is sent exactly as written instead of the agent's greeting; on a call it is given to the agent as its opening instruction for this call
templateWhatsApp only, optional — an approved template to send instead of opening_message (see below)
customer_idOptional — skip the lookup when you already know the customer

On SMS, WhatsApp and email the first message is not generated by the AI: it is your opening_message, or — when you leave it out — the greeting set on the agent's persona. The agent takes over when the customer replies.

The agent must be built for the channel ​

An agent without a Trigger for the channel you asked for is rejected. The channel a conversation arrives on shapes how the rest of the flow behaves, so starting one the agent was never built for would fail further downstream and far less clearly.

Opening with a WhatsApp template ​

Outside WhatsApp's 24-hour service window only an approved template is deliverable, so a campaign to people who have not written in today needs one:

json
{
  "agent_id": "01a0…",
  "channel": "whatsapp",
  "to": "+919876543210",
  "template": {
    "name": "order_update",
    "language": "en_US",
    "body_parameters": ["Priya", "#4182"]
  }
}
Template fieldValues
nameThe approved template's name
languageIts language code; defaults to en_US
body_parametersValues for the body's placeholders, in order
headerFor a header variable: { "type": "text", "text": "…" }, or type image / video / document with a public url
buttonsValues for the template's buttons: { "sub_type": "quick_reply" | "url", "index": 0, "payload" | "text": "…" } — index is the button's position in the approved template

Sending both template and opening_message, or a template on any channel other than WhatsApp, is refused with 400 rather than guessing which one you meant.

A phone call always opens a new conversation ​

A call is a session, not a thread — it has its own recording and its own beginning and end. History still follows the person: the same number resolves to the same customer, and the agent still sees their earlier conversations.

Text channels behave the other way round and continue an open thread, which is what replying by SMS or email means.

Check send_authorized ​

A successful request returns 201:

json
{
  "conversation_id": "01a0…",
  "execution_id": "01a0…",
  "status": "sent",
  "channel": "whatsapp",
  "send_authorized": true,
  "message_id": "01a0…",
  "provider_message_id": "…"
}
FieldMeaning
conversation_idThe conversation that was started or continued
statusFor SMS, WhatsApp and email: sent (the provider accepted it), failed (the provider rejected it), or suppressed (nothing went out — no matching Sender action, or the recipient is an automated mailbox). For a call: the dialler's status
message_idOur id for the message sent on SMS, WhatsApp or email. Absent for calls and when nothing was sent
provider_message_idThe carrier's id for the message or call; empty when it returned none

The message goes out from the number or address on the agent's Trigger, so the customer's reply comes back to the same agent. A call is placed from the number on the agent's Phone Call trigger.

There is no default sender

An agent whose Trigger names no number or address for the channel is refused with 422 no_sender_number — Perfox never falls back to some other number on your account. If your provider refuses the caller ID, the call fails rather than being retried from another number. A refused send like this is also shown to your workspace as a notification (at most once a day for the same channel, reason and sender), so you can fix the Trigger.

If an SMS or WhatsApp message fails, you aren't charged for it, and a temporary failure (such as rate limiting) is re-sent automatically. The re-send stays the same message, with the same message_id.

On email, sent only means "handed over"

SMS and WhatsApp messages move on to delivered, read or failed as the carrier reports back. An email is recorded as sent when the provider accepts it. With AWS SES, when your sending identity reports bounces to Perfox, a bounce moves the message to failed and its charge is cancelled. With every other email provider the message stays sent and a later bounce isn't reflected. Don't read sent on email as proof of delivery.

On SMS, WhatsApp and email, an agent can only send if the matching Sender action is on its canvas. When it is not, the conversation still starts and the agent still runs — but nothing goes out.

send_authorized is how you find that out. Treat false as "this agent is not finished yet" rather than as a failure of the request.

Calls are always authorized, because a call delivers over the voice stream itself rather than through a sender action.

Errors ​

HTTPCodeMeaning
400invalid_requestA field is missing or malformed
400bad_requestThe combination is not allowed — for example a template plus opening_message
402out_of_creditsYour prepaid credit balance can't fund the send. Nothing is written
404not_foundNo agent with that agent_id
422agent_not_publishedThe agent is a draft — publish it first
422no_trigger_for_channelThe agent has no Trigger for this channel
422no_sender_numberThe agent's Trigger names no number or address to send from
422destination_not_allowedAn SMS, WhatsApp or call to outside the countries Perfox may reach (India by default), or a premium-rate or special-rate number. Checked before anything is written

Error bodies carry the agent_id you sent, so a refusal can be traced without re-reading your request.