Send an outbound SMS/RCS

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>",
  "messaging_service_sid": "<string>"
}
'

import requests

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

payload = {
    "message": "<string>",
    "user_number": "<string>",
    "agent_number": "<string>",
    "messaging_service_sid": "<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>',
    messaging_service_sid: '<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>',
    'messaging_service_sid' => '<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  \"messaging_service_sid\": \"<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  \"messaging_service_sid\": \"<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  \"messaging_service_sid\": \"<string>\"\n}"

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

Sends an outbound message to the specified user number and opens a new conversation session. The endpoint handles both SMS and RCS on the same route: for SMS, send to a plain E.164 number; for RCS, prefix the recipient number with rcs: and pass a Twilio Messaging Service SID for your RCS sender in messaging_service_sid. If the recipient’s device or carrier doesn’t support RCS, delivery automatically falls back to SMS. The message behaves like a greeting, 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 or RCS 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, and RCS Business Messaging registration where applicable.

Request

Headers

string

required

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

string

required

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

string

required

Must be application/json.

Body

string

The plain-text message to send to the user. Delivered as RCS when the recipient supports it, or as SMS otherwise.

string

required

Recipient phone number in E.164 format (e.g. +14155551234). For RCS, prefix the number with rcs: (e.g. rcs:+14155551234).

string

Sender phone number in E.164 format. Must be one of the numbers provisioned for your project. If omitted, the API picks one automatically from the numbers available for the connector token’s environment. Not used for RCS — RCS senders are selected via messaging_service_sid.

string

Required for RCS. The Twilio Messaging Service SID for your RCS sender.

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

SMS

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

RCS

Outbound RCS uses the same endpoint. Prefix user_number with rcs: and pass the Twilio Messaging Service SID for your RCS sender in messaging_service_sid. If the recipient’s device doesn’t support RCS, the message automatically falls back to SMS — no extra handling needed.

cURL

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": "rcs:+14155551234",
    "messaging_service_sid": "YOUR_TWILIO_MESSAGING_SERVICE_SID"
  }'

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

SMS vs RCS delivery — SMS is sent to a plain E.164 user_number. RCS requires an rcs: prefix on user_number and a messaging_service_sid. If the recipient can’t receive RCS, delivery automatically falls back to SMS.
Agent number selection — by default the API picks from the 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 or RCS. Check Number availability & compliance for country-by-country details, throughput limits, and regulatory links before sending to a new region.

Last modified on August 19, 2026

⌘I

Send an outbound SMS/RCS

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>",
  "messaging_service_sid": "<string>"
}
'

import requests

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

payload = {
    "message": "<string>",
    "user_number": "<string>",
    "agent_number": "<string>",
    "messaging_service_sid": "<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>',
    messaging_service_sid: '<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>',
    'messaging_service_sid' => '<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  \"messaging_service_sid\": \"<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  \"messaging_service_sid\": \"<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  \"messaging_service_sid\": \"<string>\"\n}"

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

API reference

Build & deploy

Runtime & data

Monitoring

Legacy

Request

Headers

Body

Response

Example

SMS

RCS

Error response format

Notes

​Request

​Headers

​Body

​Response

​Example

​SMS

​RCS

​Error response format

​Notes

Request

Headers

Body

Response

Example

SMS

RCS

Error response format

Notes