Messaging
Create SMS Conversation
Create an SMS conversation with specific pathway state without triggering immediate message sending.
POST
/
v1
/
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"
},
"errors": null
}
Headers
Body Parameters
The E.164 formatted phone number used by the agent (must belong to the authenticated account).
Twilio message SID for tracking and correlation purposes. A request without it fails with
400 and error code MISSING_REQUIRED_FIELDS.The UUID of the current pathway being used in this conversation. On a number attached to a V2 agent, replies run the agent, not this pathway.
The ID of the current node in the conversational pathway where this conversation is positioned.
When set to true, forces creation of a new conversation, archiving any existing active conversation between these numbers.
Specifies who sent this message. Allowed values: “USER” or “AGENT”. Defaults to “USER” if not specified.
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.Per-conversation override for the message sent when the timeout fires. Takes priority over
timeout_message on sms_config/whatsapp_config.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.Per-conversation override for the warning message sent at
warning_time. Takes priority over warning_message on sms_config/whatsapp_config.Response
Ifagent_number is attached to a V2 agent whose Messages channel is turned off, for the agent or for this number, the request fails with 403 and error code CHANNEL_DISABLED.
{
"data": {
"message": "SMS conversation created successfully",
"conversation_id": "conv_abc123"
},
"errors": null
}
Docs for agents: llms.txt
Was this page helpful?
⌘I
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"
},
"errors": null
}