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 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.

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 before you go live to avoid delivery problems.

Sign in to the Twilio portal and complete the following:

1. Search for and buy a number that supports SMS.

   Tip

   You can review Twilio’s SMS pricing before you buy.

   

2. Edit the number you bought and set its messaging webhook to the Cloud Voice webhook URL you copied in Step 1.

   

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.

   

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.

   

   

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:

   

   • 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.

   

   Number and routing

   In the Number section, click Add to create a message routing rule.

   

   • 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 .

  

• 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.

  

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.