Use the Twilio integration in IU REDCap

• Overview
• Set up your Twilio account
• Enable Twilio in REDCap
• Configure Twilio settings for surveys
  • Twilio configuration settings
  • Survey-specific settings
  • Options for sending survey invitations
• Compatibility
• Troubleshoot errors
• Cost
• Privacy and security
• Get help

Overview

IU REDCap supports integration with Twilio, a third-party, vended customer engagement platform that lets organizations interact with their clients via the channels (SMS text, phone, email) they prefer. With the Twilio integration enabled in your IU REDCap project, you can securely text survey links, and send alerts and notifications to research participants directly through IU REDCap.

Set up your Twilio account

To set up a Twilio account for use in IU REDCap:

1. Purchase a Twilio user account: Go to Twilio.com to create an account, set up your payment method (free, trial accounts will not work with IU REDCap), and purchase a phone number.
   Note:

   You can have only one phone number per REDCap project. If multiple projects need Twilio, you must purchase unique phone numbers for those projects. Old phone numbers can be re-used only if the REDCap project previously using it has been deleted.
2. Disable the Request Inspector feature: To comply with IU's security requirements for sensitive data, you must disable Twilio's Request Inspector feature. This feature logs responses and stores them on Twilio's servers.
   1. From your Twilio dashboard, in the navigation menu on the left, select Programmable Voice (the telephone icon), then Settings, and then General.
   2. If prompted, authenticate with your Twilio account credentials.
   3. Under "Voice Settings", find "Request Inspector", and then toggle it from Enabled to Disabled.
   4. Capture and save a screenshot that shows Request Inspector is disabled. (You will need to provide this as part of your request to have the Twilio integration enabled in your IU REDCap project.)
   5. Scroll to the bottom of the page and choose Save.

Enable Twilio in REDCap

To allow for testing of Twilio features, you should enable the Twilio integration while your IU REDCap project is in the development phase.

To request that Twilio be enabled for your IU REDCap project, fill out the request form; include your IU REDCap project name and project ID (PID), and the following information from your Twilio account dashboard:

• Your Account SID
• Your Auth Token
• Your Twilio phone number
• A screenshot that shows that Request Inspector is disabled for your account

IU REDCap admins will enable Twilio for your project and notify you via email that you can configure Twilio in your project.

Configure Twilio settings for surveys

On your IU REDCap project's "Project Setup" page, under "Twilio SMS and Voice Call services", select Configure Twilio settings for surveys.

Twilio configuration settings

• Choose a language and voice for phone calls: Use the drop-down to select a language and a male or female voice.
• Select the modules in which Twilio will be used:
  • Surveys and survey invitations only (default)
  • Alerts & notifications only
  • ALL: Surveys and survey invitations + Alerts & notifications

Survey-specific settings

• Choose which survey invitation types to use:
  • Survey as web page:
    • Send survey invitation with survey link via SMS.
  • Survey as voice call:
    • Initiate survey as voice call
    • 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)
  • Survey as SMS conversation:
    • Initiate survey as SMS conversation
      Important:

      Only REDCap administrators can enable this option. SMS is not considered a secure form of communication. You should not administer surveys as SMS conversations if participants will be submitting personally identifiable information (PII) or protected health information (PHI) unless participants have granted you special permission to do so. Contact IU REDCap administrators, if you need to have this option enabled.
• Choose the default invitation preference for new survey participants: This value is used as the pre-selected delivery preference setting on the Participant List page when adding new participants. You can change an individual's invitation preference at any time in the Participant List.
• Control each participant's invitation preference using a multiple-choice field: Only radio or drop-down fields can be used. Each choice represents a survey invitation delivery method and must be coded as specified below:

  Required choice code	Example choice label
  EMAIL	Email invitation
  SMS_INVITE_WEB	SMS invitation (contains survey link)
  VOICE_INITIATE	Voice call (participant receives voice call)
  SMS_INVITE_MAKE_CALL	SMS invitation (contains phone number to call)
  SMS_INVITE_RECEIVE_CALL	SMS invitation (reply via SMS to receive voice call)

• Designate a phone number field for survey invitations sent via SMS or voice call (Optional): You may capture phone numbers for sending invitations to your survey participants. This can be done in addition to, or as an alternative to, entering phone numbers directly into the Participant List.
• Automatically append response instructions to questions: Use the drop-down to select whether or not REDCap should automatically append response instructions (for example, "press 1") to your survey questions.

  If your respondents will be taking the survey via one medium (web page, SMS, or voice call) only, in most cases you should set this option to No and customize the text of each question for that medium; however, if you will be using more than one medium to collect responses, setting this to Yes can provide more flexibility because REDCap will display the text appropriately for each medium.

• Behavior for overlapping SMS invitations: If you will be sending SMS invitations for multiple surveys within your project, use the drop-down to select the default behavior for handling overlapping messages.

Options for sending survey invitations

• Public survey link: If the first instrument in your project is a survey, you have the option to invite participants via voice call or SMS text.
  1. In the navigation bar on the left, select Survey Distribution Tools.
  2. Scroll to the bottom of the page, select Invite participants via Voice Call or SMS, and then enter phone numbers, one per line, select SMS delivery options, and enter a custom SMS message that participants will receive along with the link to your survey.
     Note:

     There is a message box into which you can enter survey instructions. The participant will see those instructions in the text message they receive. This is separate from the Survey Instructions that participants see when a survey link is included and they click on that to take the survey.
• Participant List: If the first instrument in your project is a survey, and you know the phone numbers of participants ahead of time, you can use the Participant List to deliver survey invitations.
  1. In the navigation bar on the left, select Survey Distribution Tools.
  2. On the Participant List tab, select Add participants.
  3. For each participant, you can enter a phone number and email address, or just a phone number. When entering both, use the drop-down to select the participant's invitation preference.
     Note:

     When adding participants to the Participant List, you can choose the default invitation preference for how they will be sent their invitations. A participant's invitation preference can be changed at any time in the Participant List. When you are ready to send survey invitations to participants, you can select the delivery method used for that batch of invitations. The preference does not have to be used when you are sending invitations, but it is provided as a convenience in case you have participants with several different invitation preferences.
• Invitation types: Invitation types available in Twilio-enabled projects are:
  • Email invitation
  • SMS invitation (contains survey link)
  • Voice call (participant receives voice call)
  • SMS invitation (contains the phone number to call)
  • SMS invitation (reply via SMS to receive voice call)
  • Use participant's preference
• Automated invitations: To use automated invitations, your project must have an instrument that contains a field for the participant's phone number, such as:
  • A data entry form into which a user enters the participant's phone number
  • A public survey link into which participants enter their phone numbers
  • A condition that will trigger the invitation

  You can choose to send automated invitations via email, SMS, or via the participant's preference.

Compatibility

Most REDCap survey features will function normally when participants take your survey via an SMS invitation; these include the enforcement of required fields, field validation, branching logic, use of 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. The Survey Login feature is one of the few survey features that is not compatible.

Troubleshoot errors

• REDCap logs invitations that have been sent in the Survey Invitation Log and indicates any errors on the far right, under "Errors (if any)":

  

  "ERROR SENDING SMS" and "ERROR MAKING VOICE CALL" are errors indicating that REDCap received an error from Twilio when attempting to send the SMS text or make the voice call. You might see these errors if you're using a test/sandbox Twilio account, your Twilio account runs out of money, or the phone number is incorrect or formatted improperly. To find more information about an error, you can check the error logs in your Twilio account.

• To protect subscribers from spam and other forms of unwanted messages, some wireless carriers apply message filtering to SMS messages. If you see a large number of invitations with a status of "Undelivered" with a "30007" error, most likely a carrier's filtering system identified a pattern in your messages that triggered a block. For more, see SMS Message Filtering in the United States and Canada in the Twilio Help Center documentation.

Cost

The Twilio integration in IU REDCap is provided at no fee. However, by using this integration, you accept full responsibility for the cost of maintaining an active user account with Twilio, which includes recurring monthly charges and usage-based charges.

For current pricing information, see:

• Twilio SMS Pricing
• Programmable Voice Pricing

Privacy and security

Although SMS messages are routed through Twilio's servers, the Twilio integration for REDCap is configured to prevent SMS metadata and transcripts from being kept in Twilio's logs. This means phone numbers and survey responses are not logged on the Twilio server. This is a HIPAA-compliance measure to protect the security and privacy of protected health information (PHI).

Because you are responsible for the security and privacy of your data, make sure to consider your use of this service in the context of your project's data security plan.

Get help

If you have questions about the Twilio integration in IU REDCap, email IU REDCap Support at redcap@iu.edu.