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

<Info>
  **Enterprise Feature** - SMS is only available on Enterprise plans. Contact your Bland representative for access.
</Info>

### Headers

<ParamField header="authorization" type="string" required>
  Your API key for authentication.
</ParamField>

<ParamField header="idempotency-key" type="string" required={false}>
  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.
</ParamField>

### Body Parameters

<ParamField body="user_number" type="string" required>
  The E.164 formatted phone number of the user receiving the message.
</ParamField>

<ParamField body="agent_number" type="string" required>
  The E.164 formatted phone number used to send the message (must belong to the authenticated account).
</ParamField>

<ParamField body="agent_message" type="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.
</ParamField>

<ParamField body="request_data" type="object" required={false}>
  Optional metadata to associate with the conversation or message. Used for custom routing or analytics.
</ParamField>

<ParamField body="new_conversation" type="boolean" required={false}>
  Allows you to create a new conversation, archiving the existing conversation and ignores existing sms messages.
</ParamField>

<ParamField body="persona_id" type="string" required={false}>
  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.
</ParamField>

<ParamField body="persona_version" type="string" required={false}>
  Which version of the persona to use. Allowed values: `"production"` (default), `"draft"`.
</ParamField>

<ParamField body="persona_settings" type="object" required={false}>
  Per-dispatch persona overrides. Takes priority over any pathway settings on the persona version or the `pathway_id` field below.

  <Expandable title="persona_settings object">
    <ParamField body="pathway_id" type="string">
      Override the persona's pathway for this dispatch.
    </ParamField>

    <ParamField body="pathway_version" type="number">
      Specific version of the override pathway to use.
    </ParamField>

    <ParamField body="start_node_id" type="string">
      Specific node to start from within the override pathway.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="pathway_id" type="string" required={false}>
  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`).
</ParamField>

<ParamField body="pathway_version" type="number" required={false}>
  Version of the pathway to use.
</ParamField>

<ParamField body="start_node_id" type="string" required={false}>
  ID of the specific node within the pathway to start from.
</ParamField>

<ParamField body="webhook" type="string" required={false}>
  This overrides the webhook for the conversation, instead of using the webhook attached to the phone number.
</ParamField>

<ParamField body="metadata" type="object" required={false}>
  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.
</ParamField>

<ParamField body="disposition_ids" type="string[]" required={false}>
  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](/tutorials/outcomes) for details.
</ParamField>

<ParamField body="citation_schema_ids" type="string[]" required={false}>
  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](/enterprise-features/citations) for details.
</ParamField>

<ParamField body="channel" type="string" required={false}>
  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](/tutorials/messaging/imessage) for details.
</ParamField>

<ParamField body="content_sid" type="string" required={false}>
  The Twilio SID of the content to send, usually in HXXXX format.
</ParamField>

<ParamField body="content_variables" type="object" required={false}>
  The variables to send with the content.
  Example:

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

<ParamField body="time_out" type="number" required={false}>
  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.
</ParamField>

<ParamField body="timeout_message" type="string" required={false}>
  Per-conversation override for the message sent when the timeout fires. Takes priority over `timeout_message` on sms\_config/whatsapp\_config.
</ParamField>

<ParamField body="warning_time" type="number" required={false}>
  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.
</ParamField>

<ParamField body="warning_message" type="string" required={false}>
  Per-conversation override for the warning message sent at `warning_time`. Takes priority over `warning_message` on sms\_config/whatsapp\_config.
</ParamField>

### Response

<ResponseField name="data" type="object">
  An object confirming the message was sent and referencing the triggered workflow.
</ResponseField>

<ResponseField name="data.message" type="string">
  Confirmation text for the successful send.
</ResponseField>

<ResponseField name="data.conversation_id" type="string">
  ID of the conversation that was created or resumed.
</ResponseField>

<ResponseField name="data.message_id" type="string">
  ID of the message that was sent, if a single message was sent, to track message delivery and status.
</ResponseField>

<ResponseField name="errors" type="null|array">
  `null` on success, or a list of error objects if the request failed.
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "message": "SMS sent successfully",
      "conversation_id": "convo_abc123",
      "workflow_id": "workflow_xyz789"
    },
    "errors": null
  }
  ```
</ResponseExample>

***

Docs for agents: [llms.txt](/llms.txt)