Skip to main content
POST
/
v1
/
outbound-sms
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>"
}
'
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

StatusDescription
202 AcceptedMessage will be sent and a conversation session will be created.
400 Bad RequestInvalid body, missing fields, bad E.164 format, or agent_number not provisioned for the project.
401 UnauthorizedMissing or invalid X-PolyAi-Auth-Token.
403 ForbiddenAPI key account does not match the connector’s account.
404 Not FoundConnector not found, or no Twilio numbers provisioned for this project.
429 Too Many RequestsPer-project rate limit exceeded.
500 Internal Server ErrorUnexpected 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"
  }'
This can lead to a conversation like:
DirectionMessage
Agent →Hi Jane, your appointment is confirmed for tomorrow at 2pm. Reply to this message if you need to reschedule.
← UserCan 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