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>",
  "metadata": {},
  "disposition_ids": [
    "<string>"
  ],
  "citation_schema_ids": [
    "<string>"
  ],
  "channel": "<string>",
  "content_sid": "<string>",
  "content_variables": {},
  "time_out": 123,
  "timeout_message": "<string>",
  "warning_time": 123,
  "warning_message": "<string>"
}
'

import requests

url = "https://api.bland.ai/v1/sms/send"

payload = {
    "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>",
    "metadata": {},
    "disposition_ids": ["<string>"],
    "citation_schema_ids": ["<string>"],
    "channel": "<string>",
    "content_sid": "<string>",
    "content_variables": {},
    "time_out": 123,
    "timeout_message": "<string>",
    "warning_time": 123,
    "warning_message": "<string>"
}
headers = {
    "authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>',
    metadata: {},
    disposition_ids: ['<string>'],
    citation_schema_ids: ['<string>'],
    channel: '<string>',
    content_sid: '<string>',
    content_variables: {},
    time_out: 123,
    timeout_message: '<string>',
    warning_time: 123,
    warning_message: '<string>'
  })
};

fetch('https://api.bland.ai/v1/sms/send', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bland.ai/v1/sms/send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>',
    'metadata' => [
        
    ],
    'disposition_ids' => [
        '<string>'
    ],
    'citation_schema_ids' => [
        '<string>'
    ],
    'channel' => '<string>',
    'content_sid' => '<string>',
    'content_variables' => [
        
    ],
    'time_out' => 123,
    'timeout_message' => '<string>',
    'warning_time' => 123,
    'warning_message' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bland.ai/v1/sms/send"

	payload := strings.NewReader("{\n  \"user_number\": \"<string>\",\n  \"agent_number\": \"<string>\",\n  \"agent_message\": \"<string>\",\n  \"request_data\": {},\n  \"new_conversation\": true,\n  \"persona_id\": \"<string>\",\n  \"persona_version\": \"<string>\",\n  \"persona_settings\": {\n    \"pathway_id\": \"<string>\",\n    \"pathway_version\": 123,\n    \"start_node_id\": \"<string>\"\n  },\n  \"pathway_id\": \"<string>\",\n  \"pathway_version\": 123,\n  \"start_node_id\": \"<string>\",\n  \"webhook\": \"<string>\",\n  \"metadata\": {},\n  \"disposition_ids\": [\n    \"<string>\"\n  ],\n  \"citation_schema_ids\": [\n    \"<string>\"\n  ],\n  \"channel\": \"<string>\",\n  \"content_sid\": \"<string>\",\n  \"content_variables\": {},\n  \"time_out\": 123,\n  \"timeout_message\": \"<string>\",\n  \"warning_time\": 123,\n  \"warning_message\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.bland.ai/v1/sms/send")
  .header("authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"user_number\": \"<string>\",\n  \"agent_number\": \"<string>\",\n  \"agent_message\": \"<string>\",\n  \"request_data\": {},\n  \"new_conversation\": true,\n  \"persona_id\": \"<string>\",\n  \"persona_version\": \"<string>\",\n  \"persona_settings\": {\n    \"pathway_id\": \"<string>\",\n    \"pathway_version\": 123,\n    \"start_node_id\": \"<string>\"\n  },\n  \"pathway_id\": \"<string>\",\n  \"pathway_version\": 123,\n  \"start_node_id\": \"<string>\",\n  \"webhook\": \"<string>\",\n  \"metadata\": {},\n  \"disposition_ids\": [\n    \"<string>\"\n  ],\n  \"citation_schema_ids\": [\n    \"<string>\"\n  ],\n  \"channel\": \"<string>\",\n  \"content_sid\": \"<string>\",\n  \"content_variables\": {},\n  \"time_out\": 123,\n  \"timeout_message\": \"<string>\",\n  \"warning_time\": 123,\n  \"warning_message\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v1/sms/send")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"user_number\": \"<string>\",\n  \"agent_number\": \"<string>\",\n  \"agent_message\": \"<string>\",\n  \"request_data\": {},\n  \"new_conversation\": true,\n  \"persona_id\": \"<string>\",\n  \"persona_version\": \"<string>\",\n  \"persona_settings\": {\n    \"pathway_id\": \"<string>\",\n    \"pathway_version\": 123,\n    \"start_node_id\": \"<string>\"\n  },\n  \"pathway_id\": \"<string>\",\n  \"pathway_version\": 123,\n  \"start_node_id\": \"<string>\",\n  \"webhook\": \"<string>\",\n  \"metadata\": {},\n  \"disposition_ids\": [\n    \"<string>\"\n  ],\n  \"citation_schema_ids\": [\n    \"<string>\"\n  ],\n  \"channel\": \"<string>\",\n  \"content_sid\": \"<string>\",\n  \"content_variables\": {},\n  \"time_out\": 123,\n  \"timeout_message\": \"<string>\",\n  \"warning_time\": 123,\n  \"warning_message\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "message": "SMS sent successfully",
    "conversation_id": "convo_abc123",
    "workflow_id": "workflow_xyz789"
  },
  "errors": null
}

POST

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>",
  "metadata": {},
  "disposition_ids": [
    "<string>"
  ],
  "citation_schema_ids": [
    "<string>"
  ],
  "channel": "<string>",
  "content_sid": "<string>",
  "content_variables": {},
  "time_out": 123,
  "timeout_message": "<string>",
  "warning_time": 123,
  "warning_message": "<string>"
}
'

import requests

url = "https://api.bland.ai/v1/sms/send"

payload = {
    "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>",
    "metadata": {},
    "disposition_ids": ["<string>"],
    "citation_schema_ids": ["<string>"],
    "channel": "<string>",
    "content_sid": "<string>",
    "content_variables": {},
    "time_out": 123,
    "timeout_message": "<string>",
    "warning_time": 123,
    "warning_message": "<string>"
}
headers = {
    "authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>',
    metadata: {},
    disposition_ids: ['<string>'],
    citation_schema_ids: ['<string>'],
    channel: '<string>',
    content_sid: '<string>',
    content_variables: {},
    time_out: 123,
    timeout_message: '<string>',
    warning_time: 123,
    warning_message: '<string>'
  })
};

fetch('https://api.bland.ai/v1/sms/send', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bland.ai/v1/sms/send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>',
    'metadata' => [
        
    ],
    'disposition_ids' => [
        '<string>'
    ],
    'citation_schema_ids' => [
        '<string>'
    ],
    'channel' => '<string>',
    'content_sid' => '<string>',
    'content_variables' => [
        
    ],
    'time_out' => 123,
    'timeout_message' => '<string>',
    'warning_time' => 123,
    'warning_message' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bland.ai/v1/sms/send"

	payload := strings.NewReader("{\n  \"user_number\": \"<string>\",\n  \"agent_number\": \"<string>\",\n  \"agent_message\": \"<string>\",\n  \"request_data\": {},\n  \"new_conversation\": true,\n  \"persona_id\": \"<string>\",\n  \"persona_version\": \"<string>\",\n  \"persona_settings\": {\n    \"pathway_id\": \"<string>\",\n    \"pathway_version\": 123,\n    \"start_node_id\": \"<string>\"\n  },\n  \"pathway_id\": \"<string>\",\n  \"pathway_version\": 123,\n  \"start_node_id\": \"<string>\",\n  \"webhook\": \"<string>\",\n  \"metadata\": {},\n  \"disposition_ids\": [\n    \"<string>\"\n  ],\n  \"citation_schema_ids\": [\n    \"<string>\"\n  ],\n  \"channel\": \"<string>\",\n  \"content_sid\": \"<string>\",\n  \"content_variables\": {},\n  \"time_out\": 123,\n  \"timeout_message\": \"<string>\",\n  \"warning_time\": 123,\n  \"warning_message\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.bland.ai/v1/sms/send")
  .header("authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"user_number\": \"<string>\",\n  \"agent_number\": \"<string>\",\n  \"agent_message\": \"<string>\",\n  \"request_data\": {},\n  \"new_conversation\": true,\n  \"persona_id\": \"<string>\",\n  \"persona_version\": \"<string>\",\n  \"persona_settings\": {\n    \"pathway_id\": \"<string>\",\n    \"pathway_version\": 123,\n    \"start_node_id\": \"<string>\"\n  },\n  \"pathway_id\": \"<string>\",\n  \"pathway_version\": 123,\n  \"start_node_id\": \"<string>\",\n  \"webhook\": \"<string>\",\n  \"metadata\": {},\n  \"disposition_ids\": [\n    \"<string>\"\n  ],\n  \"citation_schema_ids\": [\n    \"<string>\"\n  ],\n  \"channel\": \"<string>\",\n  \"content_sid\": \"<string>\",\n  \"content_variables\": {},\n  \"time_out\": 123,\n  \"timeout_message\": \"<string>\",\n  \"warning_time\": 123,\n  \"warning_message\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v1/sms/send")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"user_number\": \"<string>\",\n  \"agent_number\": \"<string>\",\n  \"agent_message\": \"<string>\",\n  \"request_data\": {},\n  \"new_conversation\": true,\n  \"persona_id\": \"<string>\",\n  \"persona_version\": \"<string>\",\n  \"persona_settings\": {\n    \"pathway_id\": \"<string>\",\n    \"pathway_version\": 123,\n    \"start_node_id\": \"<string>\"\n  },\n  \"pathway_id\": \"<string>\",\n  \"pathway_version\": 123,\n  \"start_node_id\": \"<string>\",\n  \"webhook\": \"<string>\",\n  \"metadata\": {},\n  \"disposition_ids\": [\n    \"<string>\"\n  ],\n  \"citation_schema_ids\": [\n    \"<string>\"\n  ],\n  \"channel\": \"<string>\",\n  \"content_sid\": \"<string>\",\n  \"content_variables\": {},\n  \"time_out\": 123,\n  \"timeout_message\": \"<string>\",\n  \"warning_time\": 123,\n  \"warning_message\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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

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, this generates a response using the pathway/prompt the conversation has been setup with.

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.

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.

Show persona_settings object

string

Override the persona’s pathway for this dispatch.

number

Specific version of the override pathway to use.

string

Specific node to start from within the override pathway.

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

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.

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.

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:

{
  "1": "John",
  "2": "Smith", 
  "3": "Premium Plan"
}

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.

Response

object

An object confirming the message was sent and referencing the triggered workflow.

string

Confirmation text for the successful send.

string

ID of the conversation that was created or resumed.

string

ID of the message that was sent, if a single message was sent, to track message delivery and status.

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
}

Docs for agents: llms.txt

Update SMS Configuration Send SMS Batch

⌘I

Basic Tutorials

Calls

Voices & Text to Speech

Conversational Pathways

Knowledge Bases

Numbers

Blocked Numbers

Widgets

Tools

Contacts

Memory

Node tests

Agent Testing

Evals

Guard Rails

Web Agents

Live Translation

Custom Twilio Accounts

Batches

Prompts

Account

Organizations

Messaging

SIP Trunks

Custom Dialing Pools

Personas

Citation Schemas

Alarms

Triage

Send SMS Message

Headers

Body Parameters

Response

​Headers

​Body Parameters

​Response

Headers

Body Parameters

Response