Dispatch uses Twilio as its telephony provider. Twilio provides the capability for Dispatch to send SMS messages and place voice calls.

Requirements

Using Twilio is not enabled for every client in Dispatch. If you wish to use this functionality, please complete this Workflow request to have it enabled for your client.

You have the option of using either a phone number procured from Twilio or an on-campus phone number.

Using a Twilio-provided number

A phone number procured from Twilio can be used to place voice calls or send SMS messages. Phone numbers in the 319 area code are used and registered to the Iowa City area if possible. Dispatch Support will take care of procuring a number from Twilio for you and configuring it as necessary.

Using a UI-owned number

Phone numbers owned by the University of Iowa can be used to place outgoing voice calls. In order for a UI-owned number to be used by Twilio it needs to undergo a verification process with Twilio. Dispatch Support will work with you to conduct the verification process. At this time, UI-owned phoned numbers can not be used to send SMS messages.

International SMS/Voice

By default, sending SMS messages and placing voice calls to international phone numbers (those outside the +1 calling code) are not allowed. If you have a use case, it is possible to enable sending messages and placing calls to international numbers with additional configuration when the Twilio phone numbers are procured.

API Key

In order to use Twilio to send messages, a Twilio API key needs to be assigned to your client in Dispatch. Dispatch Support will place this API key in your saved credentials so it is available to everyone who uses your client.

Twilio Pricing

Using Twilio is not free to the University of Iowa. Currently, ITS is covering the cost of using Twilio but that could change depending upon usage. Please keep that in mind when planning your communications.

Costs

See Twilio's pricing for SMS messaging and Voice calls. Phone numbers procured from Twilio also have a small monthly cost.

Cost recovery for high volume users

For high volume users of Twilio, a charge will be made to the department to recover costs. Dispatch Support will alert the owner of the Dispatch client should your usage start to require cost recovery.

How to send SMS messages

Sending SMS messages through Dispatch is not any different than sending emails. There is a destination called Twilio SMS you can choose through the Twilio SMS panel.

When sending SMS messages through Twilio, it is advisable to keep your message content as short as possible. Twilio can send a message up to 1600 characters by using message concatenation which breaks up a long message into several smaller 160 character messages. Keep in mind that Twilio charges for each message chunk sent. See SMS Character Limit in Twilio's documentation for more details.

Setting up a communication

In order to send a SMS message, your Communication Type must be set to Twilio.

SMS destination options

For SMS delivery, you need to have a Twilio SMS destination added to your communication. The following options are available for this destination type:

Messaging Service:

A messaging service allows your SMS messages to be routed in the most efficient manner to mobile carriers. Messaging services also provide access to A2P 10DLC in the United States. Selecting a messaging service replaces choosing a FROM PHONE in the communication setup.

Credentials:

The credentials you select here should be the Twilio API Key Dispatch Support has assigned you. Access to phone numbers are scoped to API Keys.

Suppression List:

Twilio supports blacklists if recipients opt out of receiving your messages. Twilio will not deliver a message to a recipient from your number if they have responded to that number with a STOP command. You have a Dispatch suppression list mirror Twilio's blacklist by selecting a suppression list. If you do not and a recipient is placed on Twilio's blacklist, you will get a delivery error if you try to send to that recipient again. See Suppression Lists for additional details.

Link Tracking:

Since SMS messages should be short, you want any links in your message to be as short as possible. Dispatch can track link clicks in SMS messages by rewriting your links just like it does for email messages. Dispatch will create as short of link as it can. If you need even shorter links, you can use a link shortening service like Bit.ly. However, the tracking will not be integrated into Dispatch. See additional documentation for limits on tracking links in SMS messages.

SMS Message Throughput

By default, all SMS messages sent through Twilio are restricted to sending one message per second. When your SMS/Voice setup is configured by Dispatch Support, a messaging service will be registered for you. The setup of your messaging service registers your use case with US-based mobile carriers and a throughput score is calculated. Some mobile carriers will allow a higher throughput while others will restrict sending to one message per second.

If higher throughput is required there are a couple options. Instead of a long code (+1 XXX-XXX-XXX), a toll-free number or a short code can be purchased for your SMS needs. A toll-free number will be able to increase your throughput to three messages per second. Higher throughput with a toll-free can be achieved at additional cost.

A SMS short code is capable of sending over a 100 messages per second. The cost starts at $1000/month.

How to place voice calls

Placing voice calls is very similar to sending SMS messages. Add a Twilio Voice destination through the Twilio Voice panel. Voice calls make use of Twillo's markup language called TwiML.

Setting up a communication

In order to send a SMS message, your Communication Type must be set to Twilio.

Voice destination options

For voice delivery, you need to have a Twilio Voice destination added to your communication. The following options are available for this destination type:

From Phone:

The phone number that your voice call will be placed from. Only phone numbers provisioned for your client are allowed.

Credentials:

The credentials you select here should be the Twilio API Key Dispatch Support has assigned you. Access to phone numbers are scoped to API Keys.

Detect human/machine:

Twilio has support for attempting to detect if a human or a machine answers the call. It is not 100% accurate. It also introduces a short pause while Twilio attempts to detect if a human answered the phone. Your options are to:

• Continue: If a machine answers the call, continue with processing the TwiML.
• Hang up: If a machine answers the call, just hang up.
• Off: Do not use any machine detection and just process the TwiML right away.

"AnsweredBy" is added to the member after the initial template is rendered in Dispatch with a value of either "human" or "machine". See additional Twilio Help for more information.

Callbacks for changes in message delivery status

For all communication types, Dispatch offers the ability to get a callback when Dispatch completes delivery to all of the destinations prescribed on the communication. For Twilio messages, Dispatch also offers the ability to get a callback when Twilio delivers the message to the recipient. If you would like these callbacks, supply an endpoint to the Message Delivery Status Change callback option field.

Handling incoming messages/calls to your Twilio number

When a Twilio number is provisioned for your use, you will need to decide how to handle incoming SMS messages and voice calls. Dispatch offers a couple of mechanisms to easily handle these incoming messages/calls, but you can also elect to handle the responses yourself.

Incoming SMS Messages

If you want to use Suppression Lists with SMS messaging, you will need to choose one of the forward options below.

Auto-reply

You can elect to have Twilio auto-reply to any incoming messages with a canned response. This response is contained in a Dispatch template for you to maintain. A typical message would be simple like "This is an automated service. Please contact 319-335-0000 for assistance.". The incoming SMS message is not relayed to you at all. It is retained in Dispatch logs for a 45 days.

Forward to email

An SMS message can be translated into email and sent to a static Population in Dispatch. This is useful for when you expect infrequent responses to the messages you send out, but there might be useful content relayed from recipients.

Forward to webhook

When you expect frequent responses to your SMS messages, this setup is ideal. Any incoming SMS messages will be forwarded to the webhook of your choice. All the member attributes associated with the last message sent to the recipient's phone number will be included in the JSON payload.

Handle yourself

Finally, you can elect to handle the response yourself. This is helpful if you want complete control of how the incoming message is processed.

Incoming Voice Calls

Suppression list use with voice calls is not supported so your options are a little more flexible on how you want to handle incoming voice calls.

Play automated message

Just like auto-replying to an SMS message with a canned response, you can play an automated message to incoming voice calls. You can either use a robotic voice to speak a message or supply a recorded audio file for playback.

Forward to another number

A popular option for handling incoming voice calls is to just forward them onto another phone number.

Handle yourself

If you want a more complex workflow for handling an incoming phone call, you can host the TwiML yourself and do more complex things like gather digits entered to forward the phone call to the approprate number, take a voice message, etc.

Using a suppression list with Twilio

There is an industry standard to allow SMS users to opt out/in of receiving SMS messages.

• To opt-out, respond with: STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT
• To start receiving messages again, respond with: START, YES
• To get help, responsd with: HELP, INFO

When a recipient of an SMS message replies to a message with message to opt-out of receiving SMS messages from you, Twilio will never send to that recipient's phone number again from the same phone number. If you attempt to send to that phone number again Twilio will return an error saying the phone number is on a blacklist. To avoid those errors, you can filter out those blacklisted numbers by using a Dispatch Suppression List. Using a Suppression List requires that incoming SMS messages are processed by Dispatch. See Handling incoming messages/calls to your Twilio number for options.