Skip to main content
POST
Create SMS Conversation

Headers

string
required
Your API key for authentication.

Body Parameters

string
required
The E.164 formatted phone number of the user in the conversation.
string
required
The E.164 formatted phone number used by the agent (must belong to the authenticated account).
string
required
The content of the message to be stored in the conversation history.
string
required
Twilio message SID for tracking and correlation purposes. A request without it fails with 400 and error code MISSING_REQUIRED_FIELDS.
string
The UUID of the current pathway being used in this conversation. On a number attached to a V2 agent, replies run the agent, not this pathway.
string
The specific version of the pathway to use (e.g., “latest”, “v1.0”).
string
The ID of the current node in the conversational pathway where this conversation is positioned.
object
Optional metadata to associate with the conversation. Used for custom routing or analytics.
boolean
When set to true, forces creation of a new conversation, archiving any existing active conversation between these numbers.
string
Specifies who sent this message. Allowed values: “USER” or “AGENT”. Defaults to “USER” if not specified.
number
Per-conversation timeout override, in seconds. When the user goes silent for this long after an agent message, the timeout flow fires (warning message and/or conversation end). Takes priority over the time_out on the number’s sms_config/whatsapp_config. Persists on the conversation, so subsequent turns use the same override until another /send or /create replaces it.
string
Per-conversation override for the message sent when the timeout fires. Takes priority over timeout_message on sms_config/whatsapp_config.
number
Per-conversation override for how long, in seconds, to wait before sending the warning message. Must be less than time_out; the request is rejected with INVALID_TIMEOUT_CONFIG otherwise. Takes priority over warning_time on sms_config/whatsapp_config.
string
Per-conversation override for the warning message sent at warning_time. Takes priority over warning_message on sms_config/whatsapp_config.

Response

object
An object confirming the conversation was created successfully.
string
Confirmation text for the successful conversation creation.
string
ID of the conversation that was created.
null|array
null on success, or a list of error objects if the request failed.
If agent_number is attached to a V2 agent whose Messages channel is turned off, for the agent or for this number, the request fails with 403 and error code CHANNEL_DISABLED.

Docs for agents: llms.txt