SMS Text and MMS Image Receiver

I. Setting up Twilio account in Way to Health

1.(red star) Contact W2H Implementation team to set up a Twilio phone number for your study.  

Is your project using using bi-directional text messaging? If yes, let the Implementation team know. With our bidirectional texting feature, you can text participants and even send and receive picture messages! 

2. Once you have the study phone number, you can set it up in Way to Health.  Navigate to Manage Study > Study Settings. Click the pencil icon to edit. 

3. Select your study's phone number from the 'Twilio voice number' and 'Twilio text number' drop down lists.  

4. Add the corresponding phone number to the 'Display phone number'. This is the phone number that will display to participants when they receive text messages from your study.  


5. If your text messages will contain PHI (ex: blood pressure readings), then you MUST select 'Delete record of all text messages from Twilio servers?'.  This will save all texts sent and received in Manage Data, but will delete the messages from Twilio. 

6. Click 'Save' 

II. Adding Bi-directional SMS as a Device

1.Navigate to the Devices under Manage Study 

2. Click add a '+New Device' 

3. Name the device and select 'Twilio SMS Receiver' from the Class drop down list.  This will auto-populate the device fields. 

4. Valid Responses box: Enter a list of valid responses that WTH will recognize when a participant texts the study by adding each response on a new line.  The response choices that you enter here will be used to build event logic in "collect data" events. Valid response choices are for non-numeric text responses only.

(lightbulb) Tip! Asking participants to send in a numeric value such as a weight or temperature? You don't need to add every potential value to the valid response box. 


  • Way to Health is NOT case sensitive
  • Do not use the response "STOP". This feature is hardcoded in WTH so that if a participant no longer wants to receive messages from the platform, they can text "STOP" at any time. If they wish to begin messaging from that phone number again, they can simply text "START" to start back up.


5. Automatic response for wrong number of incoming text messages: Type a template response that will be automatically sent to any number that texts the study if the number does not match a cell phone number in any participants' profiles. 


6. Auto response for a received text outside of an event window: If a participant sends a text message and there is no open bidirectional event, we will automatically respond with this text.  Think of this as an auto safety response! 

7. Alert to the study team for responses outside of texting event windows: Set an alert to the study team if the participant texts outside of a bi-directional event window to view the response. You can paste variables into the incident alert so your staff can troubleshoot more quickly. 

8. Click 'Add'

9. As noted in Step 1, confirm with the WTH Implementation Team that the correct URL is configured in the Twilio master account (accessible only by WTH team).


III. Set Up for Auto-Responders

In studies that do not use Bi-direction SMS (Twilio SMS Receiver) participants may reply to a Text Message they receive, and will not know we are not receiving that message. In order to accommodate this, you can configure your Twilio number to auto-response with a message telling them to call the Study line.

This is done through a service called Twimlets, which provides the auto-response service. Begin by navigating to https://www.twilio.com/labs/twimlets/echo.

At the bottom of this page, you will see an area called "Try It Out!" that allows you to put in a sample message.

Type in the message you would like to respond with (remember to keep it under 160 characters). Before the message add the tags <Response><Sms> and after the message add the tags </SMS></Response>. This is needed for Twilio to interpret the action of sending an auto-responder. 

Once you've input your message with the tags, you will see a "Resulting URL". Log in to Twilio and paste this URL into the Messaging configuration for your number (which you can access via Phone Numbers > Manage and then clicking on the number you want to edit).

Paste it into the "Request URL" box, and make sure "Configure with" is set to "URL".

Now you can test the number by texting it and ensure you get the auto-response.

(plus) Next Steps?? Set up your bi-directional SMS encounters and feedback! See Bi-directional SMS 'Collect Data' Event for more details!Â