Create SMS Conversation

curl --request POST \
  --url https://api.bland.ai/v1/sms/create \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "user_number": "<string>",
  "agent_number": "<string>",
  "message": "<string>",
  "message_sid": "<string>",
  "curr_pathway_id": "<string>",
  "curr_pathway_version": "<string>",
  "current_node_id": "<string>",
  "request_data": {},
  "new_conversation": true,
  "sender": "<string>",
  "time_out": 123,
  "timeout_message": "<string>",
  "warning_time": 123,
  "warning_message": "<string>"
}
'

import requests

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

payload = {
    "user_number": "<string>",
    "agent_number": "<string>",
    "message": "<string>",
    "message_sid": "<string>",
    "curr_pathway_id": "<string>",
    "curr_pathway_version": "<string>",
    "current_node_id": "<string>",
    "request_data": {},
    "new_conversation": True,
    "sender": "<string>",
    "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>',
    message: '<string>',
    message_sid: '<string>',
    curr_pathway_id: '<string>',
    curr_pathway_version: '<string>',
    current_node_id: '<string>',
    request_data: {},
    new_conversation: true,
    sender: '<string>',
    time_out: 123,
    timeout_message: '<string>',
    warning_time: 123,
    warning_message: '<string>'
  })
};

fetch('https://api.bland.ai/v1/sms/create', 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/create",
  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>',
    'message' => '<string>',
    'message_sid' => '<string>',
    'curr_pathway_id' => '<string>',
    'curr_pathway_version' => '<string>',
    'current_node_id' => '<string>',
    'request_data' => [
        
    ],
    'new_conversation' => true,
    'sender' => '<string>',
    '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/create"

	payload := strings.NewReader("{\n  \"user_number\": \"<string>\",\n  \"agent_number\": \"<string>\",\n  \"message\": \"<string>\",\n  \"message_sid\": \"<string>\",\n  \"curr_pathway_id\": \"<string>\",\n  \"curr_pathway_version\": \"<string>\",\n  \"current_node_id\": \"<string>\",\n  \"request_data\": {},\n  \"new_conversation\": true,\n  \"sender\": \"<string>\",\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/create")
  .header("authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"user_number\": \"<string>\",\n  \"agent_number\": \"<string>\",\n  \"message\": \"<string>\",\n  \"message_sid\": \"<string>\",\n  \"curr_pathway_id\": \"<string>\",\n  \"curr_pathway_version\": \"<string>\",\n  \"current_node_id\": \"<string>\",\n  \"request_data\": {},\n  \"new_conversation\": true,\n  \"sender\": \"<string>\",\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/create")

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  \"message\": \"<string>\",\n  \"message_sid\": \"<string>\",\n  \"curr_pathway_id\": \"<string>\",\n  \"curr_pathway_version\": \"<string>\",\n  \"current_node_id\": \"<string>\",\n  \"request_data\": {},\n  \"new_conversation\": true,\n  \"sender\": \"<string>\",\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 conversation created successfully",
    "conversation_id": "conv_abc123",
    "workflow_id": "workflow_xyz789"
  },
  "errors": null
}

POST

sms

create

Create SMS Conversation

curl --request POST \
  --url https://api.bland.ai/v1/sms/create \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "user_number": "<string>",
  "agent_number": "<string>",
  "message": "<string>",
  "message_sid": "<string>",
  "curr_pathway_id": "<string>",
  "curr_pathway_version": "<string>",
  "current_node_id": "<string>",
  "request_data": {},
  "new_conversation": true,
  "sender": "<string>",
  "time_out": 123,
  "timeout_message": "<string>",
  "warning_time": 123,
  "warning_message": "<string>"
}
'

import requests

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

payload = {
    "user_number": "<string>",
    "agent_number": "<string>",
    "message": "<string>",
    "message_sid": "<string>",
    "curr_pathway_id": "<string>",
    "curr_pathway_version": "<string>",
    "current_node_id": "<string>",
    "request_data": {},
    "new_conversation": True,
    "sender": "<string>",
    "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>',
    message: '<string>',
    message_sid: '<string>',
    curr_pathway_id: '<string>',
    curr_pathway_version: '<string>',
    current_node_id: '<string>',
    request_data: {},
    new_conversation: true,
    sender: '<string>',
    time_out: 123,
    timeout_message: '<string>',
    warning_time: 123,
    warning_message: '<string>'
  })
};

fetch('https://api.bland.ai/v1/sms/create', 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/create",
  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>',
    'message' => '<string>',
    'message_sid' => '<string>',
    'curr_pathway_id' => '<string>',
    'curr_pathway_version' => '<string>',
    'current_node_id' => '<string>',
    'request_data' => [
        
    ],
    'new_conversation' => true,
    'sender' => '<string>',
    '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/create"

	payload := strings.NewReader("{\n  \"user_number\": \"<string>\",\n  \"agent_number\": \"<string>\",\n  \"message\": \"<string>\",\n  \"message_sid\": \"<string>\",\n  \"curr_pathway_id\": \"<string>\",\n  \"curr_pathway_version\": \"<string>\",\n  \"current_node_id\": \"<string>\",\n  \"request_data\": {},\n  \"new_conversation\": true,\n  \"sender\": \"<string>\",\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/create")
  .header("authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"user_number\": \"<string>\",\n  \"agent_number\": \"<string>\",\n  \"message\": \"<string>\",\n  \"message_sid\": \"<string>\",\n  \"curr_pathway_id\": \"<string>\",\n  \"curr_pathway_version\": \"<string>\",\n  \"current_node_id\": \"<string>\",\n  \"request_data\": {},\n  \"new_conversation\": true,\n  \"sender\": \"<string>\",\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/create")

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  \"message\": \"<string>\",\n  \"message_sid\": \"<string>\",\n  \"curr_pathway_id\": \"<string>\",\n  \"curr_pathway_version\": \"<string>\",\n  \"current_node_id\": \"<string>\",\n  \"request_data\": {},\n  \"new_conversation\": true,\n  \"sender\": \"<string>\",\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 conversation created successfully",
    "conversation_id": "conv_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.

Body Parameters

string

required

The E.164 formatted phone number of the user in the conversation.

string

required

The E.164 formatted phone number used by the agent (must belong to the authenticated account).

string

required

The content of the message to be stored in the conversation history.

string

Optional Twilio message SID for tracking and correlation purposes.

string

The UUID of the current pathway being used in this conversation.

string

The specific version of the pathway to use (e.g., “latest”, “v1.0”).

string

The ID of the current node in the conversational pathway where this conversation is positioned.

object

Optional metadata to associate with the conversation. Used for custom routing or analytics.

boolean

When set to true, forces creation of a new conversation, archiving any existing active conversation between these numbers.

string

Specifies who sent this message. Allowed values: “USER” or “AGENT”. Defaults to “USER” if not specified.

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 conversation was created successfully.

string

Confirmation text for the successful conversation creation.

string

ID of the conversation that was created.

string

ID of the Temporal workflow triggered to process the conversation setup.

null|array

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

{
  "data": {
    "message": "SMS conversation created successfully",
    "conversation_id": "conv_abc123",
    "workflow_id": "workflow_xyz789"
  },
  "errors": null
}

Docs for agents: llms.txt

⌘I

Basic Tutorials

Calls

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

Create SMS Conversation

Headers

Body Parameters

Response

​Headers

​Body Parameters

​Response

Headers

Body Parameters

Response