Send an outbound SMS

POST

outbound-sms

curl --request POST \
  --url https://api.example.com/v1/outbound-sms \
  --header 'Content-Type: <content-type>' \
  --header 'X-PolyAi-Auth-Token: <x-polyai-auth-token>' \
  --header 'X-TOKEN-ID: <x-token-id>' \
  --data '
{
  "message": "<string>",
  "user_number": "<string>",
  "agent_number": "<string>"
}
'

import requests

url = "https://api.example.com/v1/outbound-sms"

payload = {
    "message": "<string>",
    "user_number": "<string>",
    "agent_number": "<string>"
}
headers = {
    "X-PolyAi-Auth-Token": "<x-polyai-auth-token>",
    "X-TOKEN-ID": "<x-token-id>",
    "Content-Type": "<content-type>"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-PolyAi-Auth-Token': '<x-polyai-auth-token>',
    'X-TOKEN-ID': '<x-token-id>',
    'Content-Type': '<content-type>'
  },
  body: JSON.stringify({message: '<string>', user_number: '<string>', agent_number: '<string>'})
};

fetch('https://api.example.com/v1/outbound-sms', 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.example.com/v1/outbound-sms",
  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([
    'message' => '<string>',
    'user_number' => '<string>',
    'agent_number' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: <content-type>",
    "X-PolyAi-Auth-Token: <x-polyai-auth-token>",
    "X-TOKEN-ID: <x-token-id>"
  ],
]);

$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.example.com/v1/outbound-sms"

	payload := strings.NewReader("{\n  \"message\": \"<string>\",\n  \"user_number\": \"<string>\",\n  \"agent_number\": \"<string>\"\n}")

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

	req.Header.Add("X-PolyAi-Auth-Token", "<x-polyai-auth-token>")
	req.Header.Add("X-TOKEN-ID", "<x-token-id>")
	req.Header.Add("Content-Type", "<content-type>")

	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.example.com/v1/outbound-sms")
  .header("X-PolyAi-Auth-Token", "<x-polyai-auth-token>")
  .header("X-TOKEN-ID", "<x-token-id>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"message\": \"<string>\",\n  \"user_number\": \"<string>\",\n  \"agent_number\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/outbound-sms")

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

request = Net::HTTP::Post.new(url)
request["X-PolyAi-Auth-Token"] = '<x-polyai-auth-token>'
request["X-TOKEN-ID"] = '<x-token-id>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"message\": \"<string>\",\n  \"user_number\": \"<string>\",\n  \"agent_number\": \"<string>\"\n}"

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

Sends an SMS message to the specified user number and opens a new conversation session. The message behaves like a greeting message, so it is fully part of the conversation context that the agent can access. If the user replies, the agent handles the conversation as a normal SMS session.

It is your responsibility to ensure that messages are sent in compliance with applicable laws and regulations, including A2P 10DLC registration for US and Canadian numbers.

Request

Headers

X-PolyAi-Auth-Token

string

required

Your PolyAI API key, provisioned in the API keys tab under your account section in Agent Studio.

X-TOKEN-ID

string

required

Connector ID for the target project. Contact your PolyAI representative.

Content-Type

string

required

Must be application/json.

Body

message

string

The plain-text message to send to the user.

user_number

string

required

Recipient phone number in E.164 format (e.g. +14155551234).

agent_number

string

Sender phone number in E.164 format. Must be one of the Twilio numbers provisioned for your project. If omitted, the API picks one automatically from the numbers available for the connector token’s environment.

Response

Status	Description
`202 Accepted`	Message will be sent and a conversation session will be created.
`400 Bad Request`	Invalid body, missing fields, bad E.164 format, or `agent_number` not provisioned for the project.
`401 Unauthorized`	Missing or invalid `X-PolyAi-Auth-Token`.
`403 Forbidden`	API key account does not match the connector’s account.
`404 Not Found`	Connector not found, or no Twilio numbers provisioned for this project.
`429 Too Many Requests`	Per-project rate limit exceeded.
`500 Internal Server Error`	Unexpected server error.

The 202 response has an empty body.

Example

curl -X POST https://api.us-1.platform.polyai.app/v1/outbound-sms \
  -H "X-PolyAi-Auth-Token: YOUR_API_KEY" \
  -H "X-TOKEN-ID: YOUR_CONNECTOR_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hi Jane, your appointment is confirmed for tomorrow at 2pm. Reply to this message if you need to reschedule.",
    "user_number": "+14155551234"
  }'

import requests

url = "https://api.us-1.platform.polyai.app/v1/outbound-sms"
headers = {
    "X-PolyAi-Auth-Token": "YOUR_API_KEY",
    "X-TOKEN-ID": "YOUR_CONNECTOR_ID",
    "Content-Type": "application/json",
}
payload = {
    "message": "Hi Jane, your appointment is confirmed for tomorrow at 2pm. Reply to this message if you need to reschedule.",
    "user_number": "+14155551234",
}

response = requests.post(url, json=payload, headers=headers)
print(response.status_code)  # 202

const response = await fetch(
  'https://api.us-1.platform.polyai.app/v1/outbound-sms',
  {
    method: 'POST',
    headers: {
      'X-PolyAi-Auth-Token': 'YOUR_API_KEY',
      'X-TOKEN-ID': 'YOUR_CONNECTOR_ID',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      message:
        'Hi Jane, your appointment is confirmed for tomorrow at 2pm. Reply to this message if you need to reschedule.',
      user_number: '+14155551234',
    }),
  }
);

console.log(response.status); // 202

This can lead to a conversation like:

Direction	Message
Agent →	Hi Jane, your appointment is confirmed for tomorrow at 2pm. Reply to this message if you need to reschedule.
← User	Can I move it to 3pm instead?
Agent →	Of course — I’ve rescheduled your appointment to 3pm tomorrow. See you then!

Error response format

All error responses return a JSON object:

{
  "detail": "A human-readable description of the error."
}

Notes

Agent number selection — by default the API picks from the Twilio numbers provisioned for your project for the environment linked to the connector token. Pass agent_number to override; it must be one of the provisioned numbers or the request is rejected with a 400.
Rate limits are applied per project. If you hit a 429, back off and retry.
Inactivity timeout — if the conversation is engaged (the user has replied), after 24 hours of inactivity a warning message is sent. If the user replies within 10 minutes, the conversation stays open and a new 24-hour inactivity timer starts. Otherwise the session terminates.
Number availability — not every country supports SMS. Check Number availability & compliance for country-by-country details, throughput limits, and regulatory links before sending to a new region.

Last modified on June 26, 2026

OverviewEnable in-browser voice conversations with PolyAI agents using WebRTC and WebSocket signaling.

⌘I

Send an outbound SMS

curl --request POST \
  --url https://api.example.com/v1/outbound-sms \
  --header 'Content-Type: <content-type>' \
  --header 'X-PolyAi-Auth-Token: <x-polyai-auth-token>' \
  --header 'X-TOKEN-ID: <x-token-id>' \
  --data '
{
  "message": "<string>",
  "user_number": "<string>",
  "agent_number": "<string>"
}
'

import requests

url = "https://api.example.com/v1/outbound-sms"

payload = {
    "message": "<string>",
    "user_number": "<string>",
    "agent_number": "<string>"
}
headers = {
    "X-PolyAi-Auth-Token": "<x-polyai-auth-token>",
    "X-TOKEN-ID": "<x-token-id>",
    "Content-Type": "<content-type>"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-PolyAi-Auth-Token': '<x-polyai-auth-token>',
    'X-TOKEN-ID': '<x-token-id>',
    'Content-Type': '<content-type>'
  },
  body: JSON.stringify({message: '<string>', user_number: '<string>', agent_number: '<string>'})
};

fetch('https://api.example.com/v1/outbound-sms', 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.example.com/v1/outbound-sms",
  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([
    'message' => '<string>',
    'user_number' => '<string>',
    'agent_number' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: <content-type>",
    "X-PolyAi-Auth-Token: <x-polyai-auth-token>",
    "X-TOKEN-ID: <x-token-id>"
  ],
]);

$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.example.com/v1/outbound-sms"

	payload := strings.NewReader("{\n  \"message\": \"<string>\",\n  \"user_number\": \"<string>\",\n  \"agent_number\": \"<string>\"\n}")

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

	req.Header.Add("X-PolyAi-Auth-Token", "<x-polyai-auth-token>")
	req.Header.Add("X-TOKEN-ID", "<x-token-id>")
	req.Header.Add("Content-Type", "<content-type>")

	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.example.com/v1/outbound-sms")
  .header("X-PolyAi-Auth-Token", "<x-polyai-auth-token>")
  .header("X-TOKEN-ID", "<x-token-id>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"message\": \"<string>\",\n  \"user_number\": \"<string>\",\n  \"agent_number\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/outbound-sms")

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

request = Net::HTTP::Post.new(url)
request["X-PolyAi-Auth-Token"] = '<x-polyai-auth-token>'
request["X-TOKEN-ID"] = '<x-token-id>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"message\": \"<string>\",\n  \"user_number\": \"<string>\",\n  \"agent_number\": \"<string>\"\n}"

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

API reference

Build & deploy

Runtime & data

Monitoring

Legacy

Request

Headers

Body

Response

Example

Error response format

Notes

​Request

​Headers

​Body

​Response

​Example

​Error response format

​Notes

Request

Headers

Body

Response

Example

Error response format

Notes