> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bland.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Send SMS Message

> Send an SMS message from an agent to a user. This creates or resumes a conversation and triggers processing workflows.

> [!NOTE]
>
> SMS is available on Enterprise plans and on the [Agent Phone Plan](https://docs.bland.ai/platform/agent-phone-plan.md). WhatsApp and iMessage are Enterprise only. Contact your Bland representative for Enterprise 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, the message is generated from the conversation's pathway, persona, or `objective`, or from the number's prompt.

**objective** `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`.

**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.

> [!WARNING]
>
> 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](#v2-agents).

**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.

**persona\_settings object**

**pathway\_id** `string`

Override the persona's pathway for this dispatch.

**pathway\_version** `number`

Specific version of the override pathway to use.

**start\_node\_id** `string`

Specific node to start from within the override pathway.

**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`).

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](#v2-agents).

**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.

**metadata** `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.

**disposition\_ids** `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](https://docs.bland.ai/tutorials/outcomes.md) for details.

Not applied on a conversation that runs a V2 agent: the API drops these IDs without an error. The agent's [Dispositions](https://docs.bland.ai/agents/dispositions.md#coming-from-citations-and-outcomes) run instead.

**citation\_schema\_ids** `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](https://docs.bland.ai/enterprise-features/citations.md) for details.

Not applied on a conversation that runs a V2 agent: the API drops these IDs without an error.

**channel** `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](https://docs.bland.ai/tutorials/messaging/imessage.md) for details.

**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:

```json theme={null}
{
  "1": "John",
  "2": "Smith", 
  "3": "Premium Plan"
}
```

**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.

### 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](https://docs.bland.ai/api-v2/post/agents-id-inbound-attach.md) or in the dashboard ([Put an agent on a phone number](https://docs.bland.ai/agents/dispatch.md#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](https://docs.bland.ai/platform/migrate-api-integrations.md), 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](https://docs.bland.ai/api-v1/post/sms-batch.md), [Create SMS Conversation](https://docs.bland.ai/api-v1/post/sms-create.md), 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](https://docs.bland.ai/tutorials/messaging/overview.md#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

**data** `object`

An object confirming the message was accepted for delivery.

**data.status** `string`

`"processing"`. The message is sent asynchronously after the response.

**data.message** `string`

Confirmation text for the accepted send.

**data.conversation\_id** `string`

ID of the conversation that was created or resumed.

**data.message\_id** `string`

ID of the message, to track its delivery and status. Returned only when the request includes `agent_message` or `content_sid`.

**errors** `null|array`

`null` on success, or a list of error objects if the request failed.

```json Response theme={null}
{
  "data": {
    "status": "processing",
    "message": "SMS accepted for delivery. Check status of SMS with the message_id",
    "conversation_id": "convo_abc123",
    "message_id": "0c9d8e7f-6a5b-4c3d-9e8f-7a6b5c4d3e2f"
  },
  "errors": null
}
```

```json 403 CHANNEL_DISABLED theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "CHANNEL_DISABLED",
      "message": "Messages are turned off for this agent."
    }
  ]
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.