Skip to main content
POST
Send SMS Message
SMS is available on Enterprise plans and on the Agent Phone Plan. WhatsApp and iMessage are Enterprise only. Contact your Bland representative for Enterprise access.

Headers

string
required
Your API key for authentication.
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

string
required
The E.164 formatted phone number of the user receiving the message.
string
required
The E.164 formatted phone number used to send the message (must belong to the authenticated account).
string
The content of the SMS message to send. If not passed in, the message is generated from the conversation’s pathway, persona, or objective, or from the number’s prompt.
string
The goal of this conversation, for example “Book a haircut for Tuesday afternoon and confirm the price.” Replies in the conversation are generated from it instead of the number’s prompt, and so is the first message when you omit agent_message. Up to 20,000 characters.A later send to the same conversation with a new objective replaces it, and a send without one keeps it. Set new_conversation to true to start a thread without it. A persona_id or pathway_id, on the request or on the number, takes priority: those replies don’t use the objective. So does a V2 agent attached to the number.An objective that is not a string, is empty, or is longer than 20,000 characters is rejected with a 400 and error code INVALID_OBJECTIVE.
object
Optional metadata to associate with the conversation or message. Used for custom routing or analytics.
boolean
Allows you to create a new conversation, archiving the existing conversation and ignores existing sms messages.
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.
The send also assigns agent_number to this persona, and the assignment stays after the send. Later texts and calls to the number run the persona. If the number was attached to a V2 agent, it no longer runs that agent. To text from an agent, attach the number to the agent and omit persona_id. See V2 agents.
string
Which version of the persona to use. Allowed values: "production" (default), "draft".
object
Per-dispatch persona overrides. Takes priority over any pathway settings on the persona version or the pathway_id field below.
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).On a number attached to a V2 agent, replies run the agent, not this pathway. If this pathway has a migration split, a new conversation can run on the split’s agent instead. See V2 agents.
number
Version of the pathway to use.
string
ID of the specific node within the pathway to start from.
string
This overrides the webhook for the conversation, instead of using the webhook attached to the phone number.
object
Custom metadata to attach to the conversation. This data is returned in all webhook payloads (message and status webhooks), making it useful for correlating conversations with your internal systems.
string[]
An array of outcome IDs to run when the conversation ends. If omitted, the outcomes configured on the SMS number are used. If provided, overrides the number’s configuration. See Outcomes for details.Not applied on a conversation that runs a V2 agent: the API drops these IDs without an error. The agent’s Dispositions run instead.
string[]
An array of citation schema IDs to extract when the conversation ends. If omitted, the citation schemas configured on the SMS number are used. If provided, overrides the number’s configuration. See Citations for details.Not applied on a conversation that runs a V2 agent: the API drops these IDs without an error.
string
The channel to send the message on. Defaults to “sms”. Allowed values: “sms”, “whatsapp”, “imessage”.For numbers provisioned for iMessage, the channel is auto-derived from the number’s configuration, so you don’t need to set this explicitly. See iMessage for details.
string
The Twilio SID of the content to send, usually in HXXXX format.
object
The variables to send with the content. Example:
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.

V2 agents

This endpoint has no agent_id parameter, and it ignores one if you pass it. A conversation runs a V2 agent in these cases:
  • The number is attached to the agent. Attach agent_number with Attach Numbers to Agent or in the dashboard (Put an agent on a phone number). Replies on the number then run the agent, even when the request includes a pathway_id.
  • A migration split routes the pathway. If the pathway the send would run has a migration split, a new conversation can run on the split’s agent, at its production version, with no change to your request. That pathway is pathway_id. When you omit it, it’s the pathway in the number’s config for the channel, or else the number’s voice pathway. The split doesn’t apply when the request has a persona_id, when the number has an agent or persona attached, or when the key isn’t an organization API key. Under the split’s default honor policy, a request that sets pathway_version or start_node_id stays on the pathway. A conversation that was already active keeps the pathway it started on, and a split never routes to an agent whose Messages channel is off. Splits apply to this endpoint only. They don’t apply to Send SMS Batch, Create SMS Conversation, or a conversation that your customer starts by texting the number.
A conversation is recorded as an agent conversation when it’s created. On that conversation, disposition_ids and citation_schema_ids don’t run, and the status webhook sent when it ends carries agent_id, agent_version_id, and agent_dispositions instead of citations and dispositions. See On a V2 agent conversation. A conversation that was already active when you attached the number isn’t recorded as an agent conversation, so its analysis and webhook shape stay V1. Set new_conversation to true to start a new one. If the number is attached to an agent whose Messages channel is turned off, for the agent or for this number, the request fails with 403 and error code CHANNEL_DISABLED.

Response

object
An object confirming the message was accepted for delivery.
string
"processing". The message is sent asynchronously after the response.
string
Confirmation text for the accepted send.
string
ID of the conversation that was created or resumed.
string
ID of the message, to track its delivery and status. Returned only when the request includes agent_message or content_sid.
null|array
null on success, or a list of error objects if the request failed.

Docs for agents: llms.txt