# Set up an SMS Channel for Twilio A Twilio SMS channel lets your agents trade text and multimedia messages with customers straight from the Cloud Voice App. This page walks you through linking a Twilio number to Cloud Voice, from grabbing a webhook URL to routing inbound messages to the right agent. ## Before you begin Confirm your Cloud Voice system meets these requirements: - **Firmware**: version **84.23.0.123** or later. - **Domain name**: the system's domain name must not contain any underscore characters. Twilio rejects underscored domains, which causes the channel to fail authentication or stop receiving messages. - **Domain certificate**: a valid domain certificate must be installed. :::caution If your Cloud Voice system uses a custom root domain rather than a standard IZT-provided cloud domain, install a valid domain certificate before you continue. Without one, the channel fails authentication or cannot receive messages. ::: ## Supported messages and limits The Twilio channel handles both plain text (SMS) and multimedia messages (MMS). Twilio decides which MMS file types it accepts; check Twilio's list of [accepted MMS file types](https://www.twilio.com/docs/sms/troubleshooting/accepted-mime-types) for the current details. Two limits apply to messages on the channel: - **Maximum file size**: 100 MB - **File retention**: 72 hours :::caution When you send an MMS, Twilio downloads the attached file from a link that your Cloud Voice system generates. If you restrict portal access by country or region (IP access protection), make sure the rule permits traffic from the country where Twilio's service is hosted. Otherwise the file transfer fails. ::: ## How the setup works Connecting Twilio takes three stages, done in order: 1. Get a webhook URL from Cloud Voice. 2. Set up a Twilio number for SMS and point it at that URL. 3. Create the SMS channel in Cloud Voice and finish its configuration. ## Step 1. Get the webhook URL from Cloud Voice A webhook URL is the address Twilio calls to hand incoming messages back to your system, so you need it from Cloud Voice before you can configure the number on Twilio. 1. Sign in to the PBX (private branch exchange) web portal and go to **Messaging > Message Channel**. 2. Click **Add** and choose **SMS**. 3. From the **ITSP** (Internet Telephony Service Provider, the carrier that handles your messages) drop-down list, select **Twilio**, then copy the **Webhook URL**. :::caution The webhook URL is regenerated as soon as you leave this page. Copy the value shown now and paste it into Twilio right away. If you navigate away, come back and copy the current URL again before configuring the number. ::: ![Cloud Voice, the SMS message channel form with Twilio selected and the Webhook URL ready to copy](/images/pbx/twilio-webhook-pce.png) ## Step 2. Set up a Twilio number for SMS :::caution Under US regulations (A2P 10DLC), any 10-digit long code (10DLC) number used for application-to-person (A2P) messaging must be registered. Messages sent to US numbers from an unregistered 10DLC number are blocked. If your business texts US customers, confirm the requirements with Twilio and [complete the number registration](https://support.twilio.com/hc/en-us/articles/1260801864489-How-do-I-register-to-use-A2P-10DLC-messaging-) before you go live to avoid delivery problems. ::: Sign in to the [Twilio portal](https://www.twilio.com) and complete the following: 1. Search for and buy a number that supports SMS. :::tip You can review Twilio's [SMS pricing](https://www.twilio.com/en-us/sms/pricing/us) before you buy. ::: ![Searching the Twilio console for a phone number with SMS capability](/images/pbx/twilio-purchase-a-number.png) 2. Edit the number you bought and set its messaging webhook to the Cloud Voice webhook URL you copied in Step 1. ![Cloud Voice, the Twilio number's messaging configuration with the webhook URL entered](/images/pbx/configure-webhook-for-twilio-pce.png) 3. Enable geographic permissions for every region you want to text, so your messages can reach numbers in those regions. :::note Set geographic permissions in the parent account. ::: ![Twilio geographic permissions with the target regions enabled](/images/pbx/twilio-geo-permission.png) 4. Open your account dashboard and note down the **Account SID** and **Auth Token**: you'll enter both in Cloud Voice in the next step. :::note Use the same account that bought the number. If you purchased the number under a sub-account, open that sub-account's dashboard to find its SID and token. ::: ![Opening a Twilio sub-account dashboard](/images/pbx/twilio-view-subaccount-dashboard.png) ![Twilio dashboard showing the Account SID and Auth Token](/images/pbx/get-account-keys-twilio.png) ## Step 3. Create the SMS channel in Cloud Voice 1. Sign in to the PBX web portal and go to **Messaging > Message Channel**. 2. Click **Add** and choose **SMS**. 3. On the **Authentication** tab, enter your Twilio credentials: ![Cloud Voice, the Authentication tab with the Twilio Account SID and Auth Token filled in](/images/pbx/twilio-auth-settings-pce.png) - **Name**: a name that helps you recognize the channel. - **ITSP**: select **Twilio**. - **Account SID**: paste the Account SID you noted from Twilio. - **Auth Token**: paste the Auth Token you noted from Twilio. 4. On the **Messaging Settings** tab, configure the channel. **Message sending rate** In the **Message Sending Rate** field, set how many messages the system may send per second. :::note - When you queue more messages than the rate allows, the system holds the extra messages and sends them at the set rate. - If your rate is higher than the limit Twilio allows on your account, messages may fail to send. Check your account's rate limit with Twilio and raise it if you need more throughput. ::: **Session settings** Configure these session options as needed: | Setting | What it does | | --- | --- | | Close Session Automatically | Closes sessions that have been idle for a set length of time. Select the checkbox, then enter the number of days in the **Session Timeout (Days)** field. | | Allow the Creation of Duplicate Active Sessions | Lets a user open a new session even when an active session with the same sender and receiver already exists. When this is on and a user starts such a session in the Cloud Voice App, a prompt appears; if the user continues, the existing session, with its full chat history, leaves its current handler's list and is taken over by the new user. | ![Enabling automatic closure of idle sessions with a session timeout set in days](/images/pbx/auto-closure-of-conversations.png) **Number and routing** In the **Number** section, click **Add** to create a message routing rule. ![Adding a message routing rule for the SMS number](/images/pbx/sms-did-number-rule.png) - **Number**: enter the number you bought, or specify an Alphanumeric Sender ID. :::note Enter the phone number in E.164 format (`[+][country code][phone number]`), for example, `+14102161183`. ::: - **Destination for Inbound Messaging**: choose where inbound messages from this number go. | Option | What it does | | --- | --- | | Extension | Routes inbound messages to one extension that you pick from the **Extension** list. Only that user receives them. | | Message Queue | Routes inbound messages for new sessions to the queue you pick from the **Message Queue** list. Every agent in the queue sees new sessions, but once an agent picks up a session, only that agent receives and answers its follow-up messages. | | Third-Party Message Analytics Platform (Transmitted via API) | Automatically forwards inbound messages to an external analytics platform over the Cloud Voice API (application programming interface) for advanced processing. Your system must already be integrated with that platform through the API before this option works. Once it is enabled, Cloud Voice transmits inbound messages to the chosen platform, and you can track them by monitoring the API event `(30031) New Message Notification`. A full Message API suite is also available for deeper message interaction; see the Cloud Voice developer documentation for details. | - **Extensions allowed to create messaging sessions**: select the extensions that may start a messaging session with customers. When the rule is complete, click **Save**. 5. Click **Save** to create the channel. ## Result - The new Twilio channel appears in the message channel list with a **Status** of connected ![connected status](/images/pbx/trunk-ok.png). ![The Twilio SMS channel listed with a connected status](/images/pbx/twilio-sms-channel-ok.png) - Cloud Voice tracks how many messages the channel sends and receives. The **Total** column counts every sent message, both successful and failed. :::note - Cloud Voice only counts messages sent from agents' Cloud Voice App clients. To work out your actual message cost, ask Twilio for the exact number of messages transmitted: long texts (over 160 characters) are split into segments for sending and reassembled on delivery, which raises the sent count. - Use the time filter to narrow the statistics to a specific period. ::: ![A message report showing sent and received message counts for the channel](/images/pbx/message-report.png) ## What to do next Send a text to the Twilio number and confirm that the agent you routed it to receives it in the Cloud Voice App.