Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.poly.ai/llms.txt

Use this file to discover all available pages before exploring further.

Prerequisites: You need a Twilio account. See the Twilio integration guide. Use SMS to extend conversations beyond voice – send confirmation codes, appointment details, links, or follow-up information that callers can reference after the call ends. SMS connects real-time voice conversations with persistent written records. Create and manage SMS templates in Build > SMS.

​
Setting up messaging

​
Connect your Twilio account

  1. Go to Build > SMS in the sidebar.
  2. Click Connect Twilio Account.
  3. In the pop-up form, fill in the following fields:
    • Account SID: Find this in the “Account Info” section of your Twilio dashboard.
    • Auth Token: Retrieve this from your Twilio account settings.
    • Twilio Phone Number: Provide the number you wish to use for sending SMS messages.
  4. Click Connect to link your Twilio account. Connect Twilio account screenshot

​
A2P 10DLC registration (US and Canada)

If you are using a US or Canadian Twilio number, you must register for A2P 10DLC to comply with carrier regulations. Without registration, Twilio blocks SMS messages entirely.
A2P 10DLC registration can take several weeks and campaigns are frequently rejected. Start this process early – do not wait until launch.

​
Register

  1. Go to Twilio’s A2P 10DLC registration page: Twilio A2P 10DLC Registration Guide
  2. Complete brand and campaign registration to comply with US and Canadian carrier regulations.
  3. Wait for approval. This typically takes several weeks. Twilio has become increasingly strict with approvals.
  4. Once approved, messages will send successfully.
Campaigns are often rejected for vague opt-in descriptions. Include detailed example conversation transcripts showing how callers consent to receiving SMS — linking a document with full sample transcripts significantly improves approval rates. A2P 10DLC is specific to US and Canadian numbers. UK and other international numbers have separate regulatory requirements – check your local carrier guidelines. Troubleshooting: If your messages fail to send, check the Twilio logs for these error codes:

​
Add SMS templates

Once connected, follow these steps to create SMS templates:
  1. Click Add SMS in Build > SMS.
  2. Fill in the form:
    • Title: A descriptive name for the SMS template (e.g., reservation_confirmation). This is the name you reference when triggering the template in functions. Max 100 characters.
    • SMS Body: The content of the message. Max 500 characters. Supports dynamic tokens (see below).
    • Phone Number: Choose the Twilio phone number associated with this message.
  3. Save the template to make it available during conversations.
Add SMS template dialog Messages of 160 characters or fewer are sent as a single SMS segment. Longer messages are split across multiple segments, which may increase cost. Keep templates concise where possible.

​
Per-environment phone numbers

Each SMS template can use a different Twilio phone number per environment, so you can test SMS in sandbox with a test number while using a production number in Live. The phone number you select in the template form applies to the Live environment. Sandbox and pre-release environments can be configured separately. This prevents test messages from being sent from your production number during development.

​
Messaging Service IDs

In addition to phone numbers, you can use a Twilio Messaging Service ID (format: MG followed by 32 hex characters) instead of a direct phone number. Messaging Services let Twilio manage number selection, compliance, and scaling automatically, which works well for high-volume deployments.

​
Dynamic tokens

You can insert dynamic values into SMS templates using the following syntax:
Token typeSyntaxExample
Variant attributes${attribute_name}${property_name}
Entities{{entity:entity_name}}{{entity:booking_date}}
Variables{{vrbl:VARIABLE_ID}}{{vrbl:CONFIRMATION_CODE}}
Example template body: 
Hi ${customer_name}, your reservation at ${property_name} is confirmed for {{entity:booking_date}}.
For multilingual projects, consider creating separate templates with language suffixes (e.g., confirmation_en, confirmation_es).

​
Managing templates

All created SMS templates are listed in Build > SMS. You can:
  • Edit: Modify the title, message content, or associated phone number.
  • Duplicate: Quickly create a copy of an existing template for similar use cases.
  • Delete: Remove unused or outdated templates.

​
Using an SMS template

  1. Go to Build > Knowledge > Managed Topics tab
    • Ensure you are on the Managed Topics tab.
  2. Add an action to a Managed Topic card
  3. Set SMS action
    • Prompt something like “If someone asks for more details, send” in the action box.
    • Click the + button on the right-hand side of the box and choose SMS > {SMS template title}.
    Here’s an example of how to construct a prompt for your agent to send an SMS: 
    After the user confirms that they would like to receive an SMS message with further details, call {{SMS_template}} to send the SMS out.
  4. Click ‘Save’ and ‘Publish’

​
Compliance keywords (STOP, START, HELP)

PolyAI automatically handles the standard SMS compliance keywords required by TCPA and carrier rules. When a recipient replies with one of these keywords, PolyAI responds and updates their opt-out status without forwarding the message to your agent. Opt-out status is tracked per (recipient number, Twilio number) pair, so a user opted out of one campaign can still receive messages from a different Twilio number.

​
Supported keywords

Matching is case-insensitive and ignores leading or trailing whitespace and a single trailing punctuation character (., !, ?, ,, ;). For example, stop, STOP., and Stop! are all treated as STOP.
KeywordAccepted variantsWhat happens
STOPSTOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUITThe sender is opted out. PolyAI replies with a confirmation and suppresses all future outbound SMS to that number from the same Twilio number until they opt back in.
STARTSTART, YES, UNSTOPThe opt-out record is removed. PolyAI replies with a confirmation and resumes delivery of outbound SMS.
HELPHELPPolyAI replies with a static help message pointing the user to STOP and START.

​
Default reply messages

KeywordReply sent to the user
STOPYou have been unsubscribed and will not receive further messages. Reply START to resubscribe.
STARTYou have been resubscribed and will receive messages again.
HELPReply STOP to unsubscribe or START to resubscribe.

​
What this means for your agent

  • Inbound STOP/START/HELP replies never reach your flows or Managed Topics. They are intercepted at the SMS handler, so you do not need to script keyword responses yourself.
  • Outbound SMS to opted-out recipients is silently dropped. If a function or Managed Topic action calls conv.send_sms or conv.send_sms_template for an opted-out number, the request returns successfully but no SMS is delivered. Check the Standard dashboard SMS widget to monitor delivery.
  • Any other inbound message from an opted-out sender is also dropped until they reply START.
  • The opt-out record persists indefinitely until the user opts back in, satisfying TCPA record-keeping requirements.
A2P 10DLC campaigns in the US and Canada require you to disclose STOP and HELP behavior during opt-in. The replies above are designed to meet that requirement out of the box.

​
Best practices

  • Keep messages short and relevant – 160 characters or fewer sends as a single segment.
  • Use variant attributes or dynamic fields (e.g., customer name, booking details) to personalize messages.
  • Disclose STOP and HELP keywords when collecting opt-in consent – PolyAI handles the replies automatically, but the disclosure is your responsibility.

​
Example: Integrating handoffs with SMS

Combine handoff functionality with SMS:
  1. The agent transfers the user to a specific agent or team using Handoffs.
  2. At the same time, an SMS template is triggered, sending the user additional details or confirmation of the transfer.

​
Integrating SMS into a function

SMS can be triggered as part of a function using the conv object:

​
conv.send_sms

Sends a free-form SMS message to a specified phone number.
# Send to the current caller
conv.send_sms(
    to_number=conv.caller_number,
    from_number="+441234567890",  # your Twilio number
    content="Your appointment is confirmed for tomorrow at 2pm."
)

​
conv.send_sms_template

Sends a pre-configured SMS template by template name (the title you defined in Build > SMS).
# Send a template to the current caller
conv.send_sms_template(to_number=conv.caller_number, template="reservation_confirmation")
The second argument is the template name (the title from Build > SMS), not an ID. For example, if your template is titled prescription_refill, use conv.send_sms_template(conv.caller_number, 'prescription_refill').
conv.send_sms_template queues the SMS for delivery rather than sending it synchronously. This means try/except blocks will not catch delivery failures – the call returns successfully even if the SMS later fails to send. To verify delivery, check conversation metadata or the Standard dashboard SMS widget.
Want to trigger SMS from Python? This page has a developer section covering conv.send_sms and conv.send_sms_template. Switch to Full docs in the top navigation to see it.

​
Delivery and logging

  • Successful SMS sends are logged in the conversation metadata.
  • Failed sends increment the API Failures metric.
  • Use the SMS widget on the Standard dashboard to monitor delivery rates.

Managed Topics actions

Trigger SMS sends from Knowledge topic actions.

Twilio integration

Connect your Twilio account to enable SMS.

Standard dashboard

Monitor SMS delivery rates with the SMS widget.
Last modified on May 19, 2026