SMS API

The SMS API lets you programmatically send SMS messages to end users and handle inbound replies through your PolyAI agent. It supports two directions:

Outbound — your system triggers an SMS to a user via the Send SMS endpoint. Each request creates a new conversation session.
Inbound — users reply to an outbound SMS (or message your agent’s number directly). The agent handles the conversation automatically over SMS. No API calls are needed from your side.

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.

The SMS API works exclusively with Twilio hosted numbers. The standard path is to purchase the number through Agent Studio, which provisions it under a PolyAI-managed subaccount and wires the inbound webhook automatically. Client-owned numbers ported into Twilio are also supported — see External Twilio numbers for the extra setup.

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

Outbound flow

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.

Inbound flow

When a user sends an SMS to one of your provisioned Twilio numbers:

Twilio routes to PolyAI

Twilio forwards the message to PolyAI via a pre-configured webhook. This webhook is set up automatically when you provision a number through PolyAI.

Session handling

If there’s an active conversation session with that user’s number, the message is added to the existing session. Otherwise, a new session is created and the agent greets the user (or processes the message directly, depending on your agent configuration).

Agent responds

The agent processes the message using the same conversation engine as voice and webchat, and sends a reply via SMS.

Inbound SMS requires Twilio webhook configuration. This is handled automatically when you provision a number through PolyAI. No additional API calls are needed — the agent handles inbound messages through the same conversation engine used for voice and webchat.

Twilio only allows one inbound webhook per number. PolyAI-provisioned numbers have that webhook pinned to /sms, which the SMS runtime relies on. If you replace it with a different webhook (for example, the external-events webhook used by the SMS data collection during a call flow), inbound SMS handling will stop working on that number.If you need both behaviors on the same agent, provision multiple numbers and dedicate each number to one webhook target. Voice and SMS can share the same number — SMS uses the messaging webhook, voice uses the voice webhook.

Session behavior

Scenario	Behavior
New user	A new conversation session is created. The agent’s start function runs with `conv.channel_type = "sms"`.
Active session exists	The message is added to the existing conversation. The agent continues where it left off.
Previous session timed out	A new session is created.
Reply to an outbound SMS	The message is added to the session created by the Send SMS endpoint. The outbound message is part of the conversation context.

Inactivity timeout

Once a conversation is engaged (at least one user reply), an inactivity timer starts:

After 24 hours of no messages, a warning message is sent to the user.
If the user replies within 10 minutes, the session stays open and the timer resets.
If no reply, the session terminates.

Channel detection

In your agent’s start function, detect inbound SMS using conv.channel_type:

def start(conv):
    if conv.channel_type == "sms":
        conv.state.greet_message = "Hi, you've reached [Company]. How can I help?"
    elif conv.channel_type == "voice":
        conv.state.greet_message = "Thanks for calling. How can I help you today?"

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. An agent can have multiple numbers attached to it, and different numbers on the same agent can be configured for different purposes (for example, one number wired to /sms for 2-Way SMS, another wired to an external-events webhook for legacy in-call SMS data collection).

External Twilio numbers

The standard path is to purchase numbers directly in Agent Studio — PolyAI provisions them under a PolyAI-managed Twilio subaccount and sets the inbound /sms webhook automatically. Client-owned numbers on an external Twilio account (either ported into a PolyAI-managed subaccount or kept on the client’s own account) are also supported, but require extra setup.

Inbound-only from a client-owned number

For inbound SMS only, you can point a Twilio number at PolyAI without registering it in Agent Studio:

In the Twilio console, set the number’s messaging webhook to your project’s /sms endpoint.
Send a test SMS to the number and confirm the conversation appears in Agent Studio’s Conversation Review tab.

The number does not need to exist in Agent Studio for inbound handling to work, but conversations tied to a number that Agent Studio doesn’t know about have limited visibility in the platform UI. For full parity (Conversation Review, analytics, handoff routing), add the number to Agent Studio.

Outbound SMS from a client-owned number

Outbound SMS via /v1/outbound-sms requires the number to exist in Agent Studio. Port the client’s number into a PolyAI-managed Twilio subaccount (or into a subaccount PolyAI has credentials for) and add it to the target agent before calling the endpoint.

AWS secret configuration for external subaccounts

When PolyAI sends SMS via a Twilio subaccount that isn’t the default platform subaccount, the runtime loads Twilio credentials from an AWS Secrets Manager secret. The secret key follows a fixed structure:

Scenario	Secret key format
Default platform account (no subaccount passed)	`<cluster>/<env>/<account-id>/twilio`
Specific subaccount	`<cluster>/<env>/<account-id>/<subaccount>/twilio`

For example, a US production account without a subaccount uses us-1/prod/<account-id>/twilio. If a subaccount is specified in the webhook configuration, the key becomes us-1/prod/<account-id>/<subaccount>/twilio. Tag the secret following the same structure as existing platform secrets (for example, uk-1/platform-prod/twilio/platform) so it is picked up by the correct environment. Contact your PolyAI representative before creating these secrets in a new account — they must line up with the connector configuration.

A2P 10DLC campaigns and sandbox testing

Twilio 10DLC campaigns are attached to a specific subaccount. Numbers provisioned via Agent Studio for sandbox go into the PolyAI-Platform subaccount, which has its own approved campaign — you can attach a sandbox number to that campaign and send test traffic. Numbers used for live client projects should be registered against the client’s own 10DLC campaign, either on their subaccount or on the PolyAI project subaccount they’ve been assigned to.

Handoff and conversation review

Conversation Review — all inbound and outbound SMS conversations appear in Agent Studio’s Conversation Review tab, alongside voice and webchat sessions.
CCaaS handoff — SMS conversations can be handed off to a human agent through the same CCaaS integrations used by webchat: NICE, Salesforce, Genesys, Webex, and Amazon Connect.
Compliance keywords — STOP, START, and HELP replies are intercepted before they reach your agent, and outbound messages to opted-out recipients are dropped silently. See Message templates for the full behavior.

Number availability & compliance

Not every country supports SMS, and the number type you use affects throughput, cost, and lead time. Before sending 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.

API reference

Build & deploy

Runtime & data

Monitoring

Legacy

Prerequisites

Base URL

Authentication

How it works

Outbound flow

Inbound flow

Session behavior

Inactivity timeout

Channel detection

Agent number selection

External Twilio numbers

Inbound-only from a client-owned number

Outbound SMS from a client-owned number

AWS secret configuration for external subaccounts

A2P 10DLC campaigns and sandbox testing

Handoff and conversation review

Number availability & compliance

Rate limits

​Prerequisites

​Base URL

​Authentication

​How it works

​Outbound flow

​Inbound flow

​Session behavior

​Inactivity timeout

​Channel detection

​Agent number selection

​External Twilio numbers

​Inbound-only from a client-owned number

​Outbound SMS from a client-owned number

​AWS secret configuration for external subaccounts

​A2P 10DLC campaigns and sandbox testing

​Handoff and conversation review

​Number availability & compliance

​Rate limits

Prerequisites

Base URL

Authentication

How it works

Outbound flow

Inbound flow

Session behavior

Inactivity timeout

Channel detection

Agent number selection

External Twilio numbers

Inbound-only from a client-owned number

Outbound SMS from a client-owned number

AWS secret configuration for external subaccounts

A2P 10DLC campaigns and sandbox testing

Handoff and conversation review

Number availability & compliance

Rate limits