> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy a Chat agent with Twilio SMS

> Prepare Twilio routing for Voiceflow’s managed SMS channel.

## Overview

Use an SMS-capable Twilio number with Voiceflow's managed SMS channel. Twilio receives the customer text and delivers the agent's reply; Voiceflow hosts the webhook and runs the assigned Chat agent. This manual prepares and checks the Twilio side, then follows the canonical [Voiceflow SMS installation](/docs/guides/channels/sms/voiceflow#connect-sms).

**Note:** 

**Other Twilio jobs:** [Deploy a Voice agent](/docs/guides/integrations/twilio/overview) for calls, or [send one text follow-up](/docs/guides/integrations/phone-messaging/send-text-follow-up) with the Twilio tool. Those connections have separate credentials and do not create an SMS agent channel.

<a id="prepare-twilio"></a>

## Prepare Twilio

Use a reply-capable number in the account you will connect.

| Input | Required configuration |
| --- | --- |
| Number | An active Twilio number with SMS capability and inbound messaging for the selected country. Use a dedicated test line before replacing an existing customer route. |
| Number credentials | The owning Account SID and Auth Token from Twilio Console. A subaccount's number needs that subaccount's credentials. |
| Sender eligibility | Complete the applicable [US A2P 10DLC](https://www.twilio.com/docs/messaging/compliance/a2p-10dlc) or [toll-free verification](https://www.twilio.com/docs/messaging/compliance/toll-free) process and check [country guidelines](https://www.twilio.com/en-us/guidelines/sms). |
| Test recipient | A separate controlled phone in an enabled destination. Trial accounts restrict recipients; complete the account's verification requirements first. |
| Existing configuration | Record the number's current messaging URL, fallback and Messaging Service association so its owner can restore them. |

In Twilio Console, open **Phone Numbers → Manage → Active numbers**, select the number and confirm its SMS capability. Obtain the credentials from its owning account's dashboard. An alphanumeric sender cannot stand in for a number customers can text back. The [Send SMS tool](/docs/documentation/build/tools/twilio-tool) uses Account SID plus API Key SID/Secret instead; do not paste that pair into number setup.

<a id="route-incoming-sms"></a>

## Route incoming SMS

Make the Voiceflow number webhook the effective inbound handler.

### 1. Connect and assign in Voiceflow

Complete [Voiceflow SMS → Connect and assign](/docs/guides/channels/sms/voiceflow#connect-sms) using Studio or Code. That procedure imports the owned number, assigns its Chat project and test Environment, and writes a **POST** messaging webhook on Twilio's IncomingPhoneNumber resource.

### 2. Inspect the resulting messaging URL

Return to the Twilio number's **Messaging configuration**. Confirm its **A message comes in** route uses the webhook Voiceflow wrote. Its shape is `https://runtime-api.voiceflow.com/v1/twilio/webhooks/PHONE_NUMBER_ID/sms`; retain the actual saved host and ID rather than reconstructing a URL from the phone's digits. Voiceflow validates `X-Twilio-Signature` against that URL and the stored Auth Token.

### 3. Resolve Messaging Service routing

If the number belongs to a Messaging Service, open that service's **Integration** settings. Select **Defer to sender’s webhook** when this number should use its Voiceflow number-level route. If the service must keep another handler, have its administrator arrange a separate number for Voiceflow. Changing the number URL alone does not override a service configured to handle incoming messages. See [Messaging Service incoming-message handling](https://www.twilio.com/docs/messaging/services#handle-incoming-messages).

Save the provider settings. Voiceflow returns an empty TwiML acknowledgment and sends the eventual agent answer through Twilio's Messages API, rather than returning the answer in webhook TwiML.

<a id="test-twilio-sms"></a>

## Test the Twilio conversation

Compare incoming and outgoing provider records with the customer exchange.

### 1. Send the known question and follow-up

Perform the [Voiceflow SMS customer test](/docs/guides/channels/sms/voiceflow#test-sms) from your separate phone. Check the expected answer and continuity in the intended Chat project's Transcript.

### 2. Inspect both message directions

In Twilio Console **Monitor → Logs → Messaging**, locate the inbound Message SID and the outgoing reply SID. Confirm `From`/`To` reverse correctly and inspect each outgoing status/error. `queued` and `sent` are intermediate evidence; compare the eventual receipt with the handset. Use [Twilio message statuses](https://www.twilio.com/docs/messaging/guides/outbound-message-status-in-status-callbacks).

### Twilio receives the text but Voiceflow does not

Check the effective messaging handler and webhook request result.

Check the number's webhook, Messaging Service inbound handling and Twilio's request error. A signature error usually requires checking the connected account credentials and actual saved URL. Keep the provider's error details and timestamp. Do not switch the voice webhook while diagnosing SMS.

### The reply is queued, rejected or undelivered

Inspect sender registration, destination permissions and opt-out state.

Check the outgoing SID's error against Twilio's documentation, account balance, approved sender, geographic permissions, trial-recipient verification and opt-out configuration. If the send result is uncertain, inspect the SID before repeating the customer action. Replaying an inbound webhook can produce another turn and another reply.

<a id="release-twilio-sms"></a>

## Release and maintain SMS

Keep the provider route and Voiceflow release aligned.

1. Complete [Voiceflow SMS → Release](/docs/guides/channels/sms/voiceflow#release-sms): publish the Chat Environment and select its **Published** version in the SMS assignment.
2. In Twilio’s Messaging configuration, confirm the number still uses the Voiceflow webhook and any Messaging Service defers to it.
3. Repeat the [customer test](#test-twilio-sms) through the final number and inspect the outgoing SID’s delivery result.

Keep replies concise. Encoding, message length, segmentation and destination rules affect delivery and cost; check [Twilio SMS character limits](https://www.twilio.com/docs/glossary/what-sms-character-limit) before introducing long or Unicode answers. Configure [opt-out handling](https://www.twilio.com/docs/messaging/tutorials/advanced-opt-out) for this sender and test it on the controlled line.

For credential rotation, unassignment and restoration of the prior handler, use [Voiceflow SMS maintenance](/docs/guides/channels/sms/voiceflow#maintain-sms). Changing an API key used by the notification tool does not rotate the stored number Auth Token. Retest voice separately if this number also takes calls.
