Skip to main content
POST
/
v1
/
sms
/
create
Create SMS Conversation
curl --request POST \
  --url https://api.bland.ai/v1/sms/create \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "user_number": "<string>",
  "agent_number": "<string>",
  "message": "<string>",
  "message_sid": "<string>",
  "curr_pathway_id": "<string>",
  "curr_pathway_version": "<string>",
  "current_node_id": "<string>",
  "request_data": {},
  "new_conversation": true,
  "sender": "<string>",
  "time_out": 123,
  "timeout_message": "<string>",
  "warning_time": 123,
  "warning_message": "<string>"
}
'
{
  "data": {
    "message": "SMS conversation created successfully",
    "conversation_id": "conv_abc123",
    "workflow_id": "workflow_xyz789"
  },
  "errors": null
}
Enterprise Feature - SMS is only available on Enterprise plans. Contact your Bland representative for access.

​
Headers

​
authorization
string
required
Your API key for authentication.

​
Body Parameters

​
user_number
string
required
The E.164 formatted phone number of the user in the conversation.
​
agent_number
string
required
The E.164 formatted phone number used by the agent (must belong to the authenticated account).
​
message
string
required
The content of the message to be stored in the conversation history.
​
message_sid
string
Optional Twilio message SID for tracking and correlation purposes.
​
curr_pathway_id
string
The UUID of the current pathway being used in this conversation.
​
curr_pathway_version
string
The specific version of the pathway to use (e.g., “latest”, “v1.0”).
​
current_node_id
string
The ID of the current node in the conversational pathway where this conversation is positioned.
​
request_data
object
Optional metadata to associate with the conversation. Used for custom routing or analytics.
​
new_conversation
boolean
When set to true, forces creation of a new conversation, archiving any existing active conversation between these numbers.
​
sender
string
Specifies who sent this message. Allowed values: “USER” or “AGENT”. Defaults to “USER” if not specified.
​
time_out
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.
​
timeout_message
string
Per-conversation override for the message sent when the timeout fires. Takes priority over timeout_message on sms_config/whatsapp_config.
​
warning_time
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.
​
warning_message
string
Per-conversation override for the warning message sent at warning_time. Takes priority over warning_message on sms_config/whatsapp_config.

​
Response

​
data
object
An object confirming the conversation was created successfully.
​
data.message
string
Confirmation text for the successful conversation creation.
​
data.conversation_id
string
ID of the conversation that was created.
​
data.workflow_id
string
ID of the Temporal workflow triggered to process the conversation setup.
​
errors
null|array
null on success, or a list of error objects if the request failed.
{
  "data": {
    "message": "SMS conversation created successfully",
    "conversation_id": "conv_abc123",
    "workflow_id": "workflow_xyz789"
  },
  "errors": null
}