Skip to main content
POST
/
v1
/
sms
/
send
Send SMS Message
curl --request POST \
  --url https://api.bland.ai/v1/sms/send \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "user_number": "<string>",
  "agent_number": "<string>",
  "agent_message": "<string>",
  "request_data": {},
  "new_conversation": true,
  "persona_id": "<string>",
  "persona_version": "<string>",
  "persona_settings": {
    "pathway_id": "<string>",
    "pathway_version": 123,
    "start_node_id": "<string>"
  },
  "pathway_id": "<string>",
  "pathway_version": 123,
  "start_node_id": "<string>",
  "webhook": "<string>",
  "channel": "<string>",
  "content_sid": "<string>",
  "content_variables": {}
}
'
{
  "data": {
    "message": "SMS sent successfully",
    "conversation_id": "convo_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.
​
idempotency-key
string
A unique key to prevent duplicate message sends. When provided, repeated requests with the same key will return successfully but will not send an additional message or incur extra charges. Useful for safely retrying failed requests without risk of double-sending.

​
Body Parameters

​
user_number
string
required
The E.164 formatted phone number of the user receiving the message.
​
agent_number
string
required
The E.164 formatted phone number used to send the message (must belong to the authenticated account).
​
agent_message
string
The content of the SMS message to send. If not passed in, this generates a response using the pathway/prompt the conversation has been setup with.
​
request_data
object
Optional metadata to associate with the conversation or message. Used for custom routing or analytics.
​
new_conversation
boolean
Allows you to create a new conversation, archiving the existing conversation and ignores existing sms messages.
​
persona_id
string
UUID of a persona to use for this conversation. When provided, the persona’s configuration is applied instead of the number’s SMS config. Use persona_version to select which version to use.Cannot be used as a substitute for agent_number — the agent number must still belong to your account. The persona_id controls how the conversation is handled, not which number sends it.
​
persona_version
string
Which version of the persona to use. Allowed values: "production" (default), "draft".
​
persona_settings
object
Per-dispatch persona overrides. Takes priority over any pathway settings on the persona version or the pathway_id field below.
​
pathway_id
string
ID of the pathway to use for generating the SMS response. If persona_id is provided, this is used as a pathway override within the persona context (lower priority than persona_settings).
​
pathway_version
number
Version of the pathway to use.
​
start_node_id
string
ID of the specific node within the pathway to start from.
​
webhook
string
This overrides the webhook for the conversation, instead of using the webhook attached to the phone number.
​
channel
string
The channel to send the message on. Defaults to “sms”. Allowed values: “sms”, “whatsapp”.
​
content_sid
string
The Twilio SID of the content to send, usually in HXXXX format.
​
content_variables
object
The variables to send with the content. Example:
{
  "1": "John",
  "2": "Smith", 
  "3": "Premium Plan"
}

​
Response

​
data
object
An object confirming the message was sent and referencing the triggered workflow.
​
data.message
string
Confirmation text for the successful send.
​
data.conversation_id
string
ID of the conversation that was created or resumed.
​
data.message_id
string
ID of the message that was sent, if a single message was sent, to track message delivery and status.
​
errors
null|array
null on success, or a list of error objects if the request failed.
{
  "data": {
    "message": "SMS sent successfully",
    "conversation_id": "convo_abc123",
    "workflow_id": "workflow_xyz789"
  },
  "errors": null
}