> ## 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. # Overview > Send SMS messages from your agent using Twilio for confirmations, links, and follow-ups **Prerequisites:** You need a Twilio account. See the [Twilio integration guide](/telephony/twilio/introduction). 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**](https://help.twilio.com/articles/14726256820123-What-is-a-Twilio-Account-SID-and-where-can-I-find-it-): Find this in the "Account Info" section of your Twilio dashboard. * [**Auth Token**](https://www.twilio.com/docs/iam/api/authtoken): 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](https://www.twilio.com/docs/messaging/compliance/a2p-10dlc#who-needs-to-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](https://help.twilio.com/articles/1260800720410-What-is-A2P-10DLC-) 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: * [**30034** - Unregistered Number](https://www.twilio.com/docs/api/errors/30034) * [**30035** - Number Still Being Configured](https://www.twilio.com/docs/api/errors/30035) ### 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 type | Syntax | Example | | ------------------------------------------------------ | ------------------------ | ---------------------------- | | [Variant attributes](/variant-management/introduction) | `${attribute_name}` | `${property_name}` | | Entities | `{{entity:entity_name}}` | `{{entity:booking_date}}` | | Variables | `{{vrbl:VARIABLE_ID}}` | `{{vrbl:CONFIRMATION_CODE}}` | Example template body: ```plaintext theme={"theme":{"light":"github-light","dark":"github-dark"}} 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](/managed-topics/introduction)** * Ensure you are on the Managed Topics tab. 2. **Add an action to a Managed Topic card** * In any Managed Topic card, click ["Add Actions."](/managed-topics/how-to-setup-action/send-sms) 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: ```plaintext theme={"theme":{"light":"github-light","dark":"github-dark"}} 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](https://www.fcc.gov/sites/default/files/tcpa-rules.pdf) 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`. | Keyword | Accepted variants | What happens | | --------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **STOP** | `STOP`, `STOPALL`, `UNSUBSCRIBE`, `CANCEL`, `END`, `QUIT` | The 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. | | **START** | `START`, `YES`, `UNSTOP` | The opt-out record is removed. PolyAI replies with a confirmation and resumes delivery of outbound SMS. | | **HELP** | `HELP` | PolyAI replies with a static help message pointing the user to `STOP` and `START`. | ### Default reply messages | Keyword | Reply sent to the user | | ------- | ----------------------------------------------------------------------------------------------- | | STOP | `You have been unsubscribed and will not receive further messages. Reply START to resubscribe.` | | START | `You have been resubscribed and will receive messages again.` | | HELP | `Reply 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](/analytics/dashboards/standard) 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](/call-handoff/introduction) 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](/tools/introduction) using [the `conv` object](/tools/classes/conv-object): ### `conv.send_sms` Sends a free-form SMS message to a specified phone number. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} # 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**). ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} # 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](/analytics/dashboards/standard) 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](/analytics/dashboards/standard) to monitor delivery rates. ## Related pages Trigger SMS sends from Knowledge topic actions. Connect your Twilio account to enable SMS. Monitor SMS delivery rates with the SMS widget.