How do I setup Twilio to send SMS text messages and voice calls?

Owned by Christopher Sorensen
Dec 30, 2023
5 min read

Before you begin using Twilio, please note that it is an outside vendor software and Washington University provides NO support for Twilio.

REDCap has the capability to utilize a third party SMS and voice call service called Twilio for sending survey invitations via SMS text messages and also for having respondents take surveys via a voice call or SMS.  With this feature enabled, you can invite a participant to take a survey by sending them an SMS message or by calling them on their phone.  The participants can then take your surveys, either as a voice call survey or as an SMS message conversation.  The survey data would then be collected in REDCap directly from their phone without having to use the website.  

SETUP & CONFIGURATION:  Before you begin the setup steps below, you must:

  1. Register and setup up your own Twilio account at www.twilio.com. 

  2. Fund your account with some money using the Billing page in Twilio (since there is a cost for each phone call made and for each SMS message sent and

  3. Purchase a phone number to be used for this REDCap project (see the Numbers page in Twilio).  Each project must have its own number.

Once you have a phone number setup in Twilio for your project, you will need to send an email to the REDCap administrator (redcap_helpdesk@wustl.edu) with the following information:

  1. Twilio Phone Number

  2.  Twilio Auth Token

  3.  Twilio Account SID

(see the API Credentials section on the Twilio main Account Settings page)

Note: Please ensure you have DISABLED Twilio's 'Request Inspector' for this account:
A Twilio feature named Request Inspector causes all activity to be logged in detail and stored on Twilio's servers. For the highest level of privacy, it MUST BE DISABLED in your Twilio account in order to be able to utilize the Twilio services in REDCap. You will find this setting on the Configure page under 'Programmable Voice'

Once your receive a confirmation email back from your REDCap administrator that your project is connected to your Twilio account, you can then configure how you want to use Twilio in your project. In general, not much is different between administering a survey normally in REDCap than when using Twilio SMS/voice calls except that you additionally choose how your survey invitations are delivered. The following choices are available:

  • Initiate survey as voice call

  • Initiate survey as SMS conversation

  • Send survey invitation with survey link via SMS

  • Send survey invitation via SMS to take survey as voice call (respondent makes call)

  • Send survey invitation via SMS to take survey as voice call (respondent receives call when replying via SMS).

Any or all of these invitation delivery methods can be utilized within a single project. The choice of delivery method completely depends upon your specific use case for how you want to collect data from your participants.  It is NOT recommended to use option 

 

VOICE CALL SURVEYS: When participants take a survey as a voice call, questions are asked one at a time, in which the Twilio service will use text-to-speech technology to read the questions to the participant audibly on their phone. You may choose the language and/or dialect in which the text should be read. Participants will respond by entering numbers on their phone's keypad, thus only numeric responses can be used because of this limitation (this includes the use of integer/number fields and also multiple choice questions with numeric codings, in which the participant will enter the numeric coded value on their keypad, not the label that is read to them over the phone). For example, the question might be a Yes-No question, which might look like 'Do you like ice cream? Yes, press 1. No, press 0.', or a number question like 'What is your age?'.

 

SMS SURVEYS: When participants take an SMS survey, questions are asked one at a time as an SMS text message conversation/thread. SMS surveys provide more response possibilities than voice calls. While participants in voice calls can only respond with numbers, they may respond with any kind of alpha-numeric text for an SMS survey.

Note:  Only REDCap administrators are allowed to enable the Twilio option to initiate a survey as an SMS conversation. Much like email, SMS is not considered a secure form of communication, so you may not want to administer surveys as SMS conversations if the particpant will be submitting identifying information (PHI or PII) unless you have been granted special permission from the participant to do so. Given such sensitive privacy issues, only your local REDCap administrator can enable the optional setting to use SMS surveys. Please notify your administrator about this if you wish to have this option enabled.

 

COMPATIBILITY: Most of REDCap's survey features still function much the same when taking a survey via SMS or as a voice call. This includes the enforcement of required fields, field validation, branching logic, using the Survey Queue for multiple surveys (only works with Auto-Start enabled), survey email notifications and confirmations, the Participant List, Automated Survey Invitations, survey Stop Actions, and computer adaptive tests (CATs) downloaded from the REDCap Shared Library. One of the few survey features that is not compatible is the Survey Login feature.

COST: In order to use the Twilio SMS and Voice Call services in a REDCap project, you will have to connect your project to your Twilio account by entering your Twilio credentials into REDCap during the setup process. And as REDCap makes calls and/or sends SMS messages using this service, all charges to your Twilio account will be made based upon its usage. This is not done by REDCap but is done internally by Twilio as you use its services. In this way, no monetary transactions are made by REDCap, and thus it is your responsiblity to maintain the funds in your Twilio account in order to ensure that the service continues to work for your REDCap project. If your Twilio account runs out of funds, the Twilio services in REDCap will cease to function. For information on the cost of each call or each SMS message, visit your Twilio account to view the rates.

PRIVACY & SECURITY INFO: It is important to understand that this feature utilizes the third-party service http://Twilio.com , which means that all voice calls and SMS messages will be routed through Twilio's servers. However, REDCap goes to great length to ensure that voice call records and SMS transcriptions do not stay in Twilio's logs but are removed shortly after being completed. This is done for security and privacy concerns (e.g., HIPAA), in which your survey participants' phone numbers and their survey responses do not get permanently logged on Twilio's servers but instead remain securely in REDCap.

IRB COMPLIANCE:  All projects requiring IRB approval must report to the IRB that their project utilizes Twilio.