Tips for Getting Started

There is not a definitive place to get started with using Twilio. Instead, there is a list of things that need to get done before the REDCap Team can help you set up your project to use your Twilio account. The following four items, Request Twilio for Your Project, Set up Twilio Account and Purchase Number, Address Regulatory Requirements, and Prepare to Meet with REDCap Team, are not presented in a linear fashion, as in Step 1, Step 2, Step 3, Step 4. The order in which these items are completed is at the discretion of you and your team. Note, you must have access to billing information, to set up your Twilio account and send your Twilio request form to the REDCap team.

Request Twilio for Your Project

Requesting Twilio for your project is a two-step process. The project point person is expected to complete the forms described below, and will need to know the Alias, FAID and name of the FAID owner that can be submitted for the costs associated with REDCap team assistance (separate from direct vendor charges).

• Step 1
  • Complete the request Twilio Request form in the REDCap project you plan on using Twilio for.
    • Find the button to open the form in the Project Setup tab > Enable optional modules and customizations > Twilio Request button


  • Submit project and billing information, including Alias and FAID numbers and the name of the FAID owner.
    
    
• Step 2
  • The REDCap Team processes the request and sends the requestor a link to a form that has both:
    • Instructions for setting up a Twilio account and purchasing a number, and
    • Fields for collecting the Twilio account information. Please see below.  
  • Submit the form after:
    • The Twilio number has been purchased
    • The account has been funded
    • The registering the brand campaign has been completed. More information on this is listed below.

Set up Your Twilio Account and Purchase a Twilio Number

Visit Twilio.com and complete the following tasks:

Set up a Twilio account.

• Trial or test accounts cannot be used with a REDCap project.

Fund your account Twilio account via the Billing page.

• Your Twilio account must be funded.
• The Twilio module will not work with a demo account.

Purchase a number via the Phone Numbers page.

• Find Phone Numbers in the Products & Services sub-menu by clicking the circle with three dots inside it in left hand navigation
• Twilio in REDCap can only be used for texting. The number does not need voice or faxing capabilities.
• A single Twilio number cannot be used for multiple REDCap projects.
• Tip: some study teams have reported that there are fewer issues with toll free numbers being blocked by mobile providers and phone carriers.

If purchasing a toll-free number, Twilio requires additional verification before the number will be approved including:

• Screenshot of the electronic survey where end users provide their phone number and opt-in to SMS messaging.
• Photo or screenshot of the keyword or QR code where end users opt-in to SMS messaging.
• Screenshot documenting if users opt-in to SMS messaging via voice, such as a checkbox on a form.
• Scan or photo of the paper form where end users opt-in to SMS messages.

Disable the Request Inspector

• The Twilio feature named the 'Request Inspector' causes all activity to be logged in detail and stored on Twilio's servers. 
• To disable the Request Inspector in your Twilio console:
  • Find the Request Inspector on the Settings page, under Programmable Voice. Once there, disable the Request Inspector and click Save. 

Register your brand and campaign with Twilio.

• For local numbers, expect this process to take between 2-4 weeks.
• For toll-free numbers, expect this process to take between 6-8 weeks.

Address Regulatory Requirements for Using Twilio

Describe Using Twilio in Your Protocol

Add the following language to your protocol: Survey invitations and reminders will be sent by email or SMS text message [specify the method(s)] to study participants.

Describe Using Twilio for Sending Survey Invitations in Your Consent 

The following language was provided by the IRB.

Submit your Text Invitations for IRB Approval

All SMS messages should be submitted to the IRB for approval. The guidance, below, regarding content is regulated by OHSU's IRB and OHSU's IPS office.

• Do not include participant identifiers other than the participant provided phone number.
• Do not include specific care information (e.g., meds, diagnoses/conditions, etc.).
• Do not include study names or email addresses that could link a participant to a health care condition or disease. 

All SMS texts that do not meet these standards must go through an IPS policy exception process. 

Prepare for Meeting with the REDCap Team

Preparing your to meet with the REDCap Team involves both getting your project ready for using Twilio, getting your project ready to work on survey invitations, and planning for how to work with the REDCap to contextualize the Twilio configuration in the your project's setup

Twilio Configuration Considerations

The default configuration for projects using Twilio is to use a Survey Management data entry form to record each enrolled participant's current opt-in decision for texting, as well as their preference for receiving survey invitations. Both the opt-in decision and the preference of each participant will be used as conditions (logic) for sending survey invitations to participants. Before the study team can text an SMS survey invitation to a participant, a participant must consent to the study and explicitly opt in to texting. Additionally, participants can always opt-out of receiving texts later, and they can exert a preference for receiving email invitations instead of text invitations. For this reason, a Survey Management form is used to enable the study team to maintain the current opt-in status and preference of each participant through the life of the study. 

If receiving text invitations is part of your study's intervention, and individuals cannot participate in your project if they opt out of receiving texts, the REDCap Team will work with you to set up your project to meet these requirements.

Considerations for How the Twilio Configuration Works in Conjunction with Surveys and Survey Invitations

• For any invitations that the study team manually compose and schedule, email will be the default method for sending the invitation, but the study team can opt to change the send method to SMS.
  
  
• For the Automated Survey Invitations (ASI) the study team builds, when Twilio is enabled, the following a new setting appears in the ASI definitions: Invitation Type. This new setting defines the method for sending the invitation to the all the participants eligible to receive the invitation. There are three Invitation Types: 1) Email, 2) SMS, and 3) Use participant's preference. The table here illustrates how the system will deploy an invitation depending on the Invitation Type and Participant Preference settings. 

• • Invitation Type	Participant Preference	Invitation Sent Via
    Email	Email	Email
    Email	SMS	Email
    SMS	Email	SMS
    SMS	SMS	SMS
    Use participant's preference	Email	Email
    Use participant's preference	SMS	SMS

    
    
    
  • For invitations that can be sent via text, the default recommendation is to set up the Invitation Type to Use participant's preference. That way the study team can account for individual participant's opting out of texting or changing their preference by updating fields in a the participant's, instead of manually deleting and rescheduling invitations for the participant.
    
    
• For surveys with Save and Return enabled

  • The Save & Return message, generated by REDCap, is sent to the participant’s email address, as designated in REDCap, not their phone number.

  • If an email address has not designated for the project or the survey, the participant will be prompted to enter an email address to receive the Save & Return message.

 Project Specific Preparations for Building Automated Survey Invitations

• Finalize the main project settings. 
  • i.e. if a survey is repeated at different time points, longitudinal is enabled, events have been created for the time points and surveys have been assigned to the event
• Build and test any forms that will impact survey deployment/survey collection.
• Build and test all surveys.
• Create test records the REDCap Team can use for testing
  • These records should represent participants eligible for the surveys (but the surveys should not yet be completed).

Twilio Specific Preparations

Two Requirements

• Capture the participant's phone number in a phone number validated text field.
  
  
  
• Capture the participant's opt-in decision for texting in a radio button field.
  

  • The IRB requires that opt-in language for texting be must delivered to the participant and received by the study team in writing. Options for accomplishing this include in a REDCap survey, e-mail to study team, letter, etc.

  • To include opt in language on a REDCap survey, add a radio button with the following attributes 
    
    • Field Type: Multiple Choice - Radio Buttons (Single Answer)
    • Field Label: I agree to receive text messages for this study and understand that OHSU cannot guarantee they will be confidential.  
    • Choices
      • 1, Yes, I agree
      • 0, No, I decline


• Optionally: Capture the participant's preference for receiving survey invitations in radio button field with the following attributes: 
  
  • Field Type: Multiple Choice - Radio Buttons (Single Answer)
  • Field Label: Default invitation preference  
  • Choices
    • EMAIL, Email invitation
    • SMS_INVITE_WEB, SMS invitation (contains survey link)




Best Practices 

If your study plans on using REDCap for collecting the data above directly from the participant via a survey, use of a data entry field to manage surveys is the best practice, see above under "Twilio Configuration Considerations." If you are using REDCap for e-consenting, the best practice is to collect the items in a survey that follows e-consent, then work with the REDCap Team to pipe these values into a data entry form the staff can use for survey management. Piping these values into corresponding fields in data entry form removes the possibility of directly editing a participant reported survey (never recommended) and reduces the chance of the study staff overwriting any other responses that may be collected in the same survey as the items above. Additionally, if you added a radio button to capture the participant's opt-in decision for texting to your e-consent, it is an IRB requirement that the e-consent survey can't be updated, to reflect a participant changing their initial decision, you must have a method to manage that change elsewhere. 

Meet with the REDCap Team - Meeting 1

Before the meeting the REDCap Team member will enter the Twilio account information you submitted during the request process (see above under "Request Twilio For Your Project, Step 2") into your REDCap project and try to text themselves an SMS invitation. If the invitation fails to send, this typically means that all the registration steps have not been completed, or the account is not funded. The team member will contact you in the event this happens.

Meeting Overview

• Meeting Duration: 1 hour
  
  
• Meeting Focus: The focus of the first meeting is to configure your project to use your Twilio account and start work on your Automated Survey Invitations. 
  
  By default every project is configured for the study staff to record in a data entry form each enrolled participant's opt-in decision for texting, as well as their preference for receiving survey invitations, both of which will be used as conditions for texting SMS survey invitations to participants. This is because before the study team can text a participant an SMS survey invitation, a participant must consent to the study and explicitly opt in to texting. Additionally, a participant can always opt out of receiving texts, and even for participants who do opt in to receiving texts, they can still exert a preference for receiving email invitations instead of text invitations.
  
  
• Note: You will need to have access to the Twilio account during this meeting.

Standard Agenda

Below is the standard agenda the REDCap Team works from for the first meeting.

Twilio Specific

• Review how study team's Twilio account information is captured in the project.  
• Confirm request inspector has been disabled.
• Review in what form or survey the following information is being captured:
  • Participant's phone number
  • Participant's opt-in decision for texting
  • Participant's preference for receiving survey invitations
  • If these item are collected in one or more survey's, pipe the responses into corresponding fields in a Survey Management form.
• Configure the Twilio project settings
• Manually text an SMS survey invitation to the point person
  • Point person confirms they received the text
• Create test records to demonstrate how the participant's preference for invitations is stored in the Participant List.
• Demonstrate that Twilio numbers are not monitored for incoming texts or phone calls.
  • Point person confirms this by replying to SMS invitation and review response with point person
• Set up generic response for any participant text replies and test response
  
  Instructions for adding an Auto-Responder to Your Twilio Account for Incoming Texts

  • Log into Twilio
    
    
  • In the left hand navigation menu, scroll to the bottom and click Explore Products.
    
    
    
  • On the Explore Products page, scroll down to Developer Tools and click TwiMl Bins.
    
    
    
  • On the TwiML Bin page, click the blue + sign
    
    
    
  • Configure a TwiML 
    
    • Friendly Name = enter a name for the auto-responder such as (Name of your study) Auto-Responder
    • TwiML =
      <?xml version="1.0" encoding="UTF-8"?>
<Response>
<Message>Your contact info</Message>
</Response>
      
    • The <message> is the participant-facing messaging and must be approved by the IRB.
      
      

  • Scroll down and click the blue Create button.
    
    
    

  • Navigate to your phone number using one of the following methods:
    
    • Method 1
      • Click on the Dashboad link at the top of the left hand navigation menu
      • On the Dashboard page, scroll down to the Account info
      • Click on the View all numbers link next to the your twilio phone number
        
        
    • Method 2
      • Click on the Phone numbers near the top of the left hand navigation menu
      • In the expandable menu, click on the Manage link
      • In the expandable Manage menu, click on the Active Numbers link
        
        
        
  • Click the number to which you want to add the auto-responder message
    
    

  • On the phone number page, scroll down to the Messaging Configuration section:

    • Configure With dropdown menu =  Webhook, TwiML Bin, Function, Studio Flow, Proxy Service
    • A Message Comes in = TwiML Bin
    • TwiML Bin = The option identified by the Friendly Name you provided in step 5
    • Click the blue Save Configuration button.
      
      
      
  • Test that your auto-responder is working by sending a text message to your Twilio number.
• Review some Twilio nuances
  • How automated Save and Return message works for surveys participant was invited to texting an SMS.
  • How Twilio charges for messages sent and received.

Automated Survey Invitations (ASI)

• Review how the Twilio configuration works in conjunction with the ASI setup.
• Gather requirements for surveys that can be sent via text and if the project is set up to meet the requirements

For many projects Meeting 1 ends here, especially if the project setup issues are identified that impact meeting the requirement for survey deployment or if issues were identified earlier during Twilio configuration that required some restructuring of the project.

Bonus Activities (if set up is smooth and time allows)

• Set up at least one ASI with a pattern that the point person can implement in other ASIs.
• Test the ASI and review how to test the ASI.
• If time allows set up and test ASIs for other surveys.

Meet with the REDCap Team - Meeting 2

Before the meeting if any ASI's were set up, the REDCap Team member will check if some testing has been completed. In the event testing is incomplete, the REDCap team member will contact you to re-scheduling the meeting.

Meeting Overview

Meeting Duration: 1 hour

Meeting Focus: The focus of the second meeting is to address any project setup issue that were identified in Meeting 1 and start/or continue work on the Automated Survey Invitations (ASI) for the surveys that can be sent via text. Depending on the complexity of the survey deployment requirements and the number ASIs that need to be set up, the effort to define and test ASIs can be significant. 

Standard Agenda

Project Setup Issues, if they were identified in Meeting 1

• Follow up any issues that were identified that needed to be addressed before building out ASIs.

Automated Survey Invitations

• Review testing on ASI that completed after Meeting 1
• Review any ASI that were created after Meeting 1
  • Spot test ASI
• Define new ASIs
  • Test ASIs
  • Review how to test ASIs
  • Review with point person how to implement new ASI patterns
    
    

Meet with the REDCap Team - Meeting 3

Before the meeting the REDCap Team member will check if some interim testing has been completed, based on the work completed in Meeting 2. In the event testing is incomplete, the REDCap team member will contact you to re-scheduling the meeting.

Meeting Overview

Meeting Duration: 1 hour

Meeting Focus: The focus of the third meeting is to finalize work on the Automated Survey Invitations (ASI) for the surveys that can be sent via text. Depending on the complexity of the survey deployment requirements and the number ASIs that need to be set up, the effort to define and test ASIs can be significant.

Standard Agenda

Automated Survey Invitations

• Review testing on ASI that completed after Meeting 2
• Review any ASI that were created after Meeting 2
  • Spot test ASI
• Define new ASIs
  • Test ASIs
  • Review how to test ASIs
  • Review with point person how to implement new ASI patterns