The Outbound SMS API lets you programmatically send SMS messages to end users through your PolyAI agent. Each request creates a new conversation session — the agent delivers the message via Twilio and can handle any replies from the user.
Prerequisites
- An API key provisioned via Agent Studio — create one in the API keys tab under your account section (passed as
X-PolyAi-Auth-Token)
- A connector ID for the target project (passed as
X-TOKEN-ID). Contact your PolyAI representative.
- At least one Twilio phone number provisioned for the project. The API automatically selects from the project’s available numbers for the token’s environment (dev, sandbox, live) unless you specify one via
agent_number.
Base URL
Replace <cluster> with the region for your deployment:
| Cluster | Region | Base URL |
|---|
us-1 | United States | https://api.us-1.platform.polyai.app |
uk-1 | United Kingdom | https://api.uk-1.platform.polyai.app |
euw-1 | EU West | https://api.euw-1.platform.polyai.app |
Authentication
All requests require two headers for authentication:
curl -X POST https://api.<cluster>.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"
How it works
- Send message — POST to
/v1/outbound-sms with the recipient number and message text.
- Session created — The API creates 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.
- User replies — If the user replies, the agent handles the conversation as a normal SMS session.
- Inactivity timeout — If the conversation is engaged (the user has replied) and goes idle for 24 hours, a warning message is sent. If the user replies within 10 minutes the session stays open; otherwise it terminates.
Agent number selection
By default the API picks from the Twilio numbers provisioned for the connector token’s environment. You can override this by passing agent_number in the request body — the number must be one of the provisioned numbers or the request is rejected with a 400.
Number availability & compliance
Not every country supports SMS, and the number type you use affects throughput, cost, and lead time. Before sending outbound SMS in a new country, check Number availability & compliance for country-by-country details, regulatory links, and the A2P Campaign Pre-Scanner to validate your setup against carrier requirements.
For US and Canadian numbers, A2P 10DLC registration is required — carriers block messages entirely without it.
Rate limits
Rate limits are applied per project. If you receive a 429, back off and retry with exponential backoff. Last modified on June 26, 2026
