Setup an SMS Survey

One of the primary uses of CommCare Messaging is to send out surveys via SMS.

Some common use cases:

  • Asking a patient if they have taken their medication

  • Asking a community health worker some questions about their most recent visit

Surveys are very easy to build because they use the same Form Builder as CommCare.

1. Getting Started

Navigate to the tab that is called "Applications."

You can find basic information about the Form Builder here or in the Beginner Tutorial. It is highly recommended that you complete the Beginner Tutorial before proceeding.

2. Design your Survey


Please do not make the first question in your SMS survey a question list. This may lead to errors in the sending of the SMS survey.

Please note that the following are not supported in SMS surveys:

  1. 'commcaresession' instances and 'location' instances are not supported in SMS surveys

  2. referencing lookup tables are not supported in SMS surveys (via conditional alerts). thorough testing is strongly recommended.

Referencing the Form Builder Page, you can think through the different types of questions you may want to include in your survey, and how you want the structure of your survey.

The most common question types for SMS Surveys are:

  • Text

  • Multiple Choice - Single Answer

  • Multiple Choice - Multiple Answer (Checkbox)

  • Label - is a message that does not require any action- it is only to provide information

Be sure to consult the CommCare Messaging best practices for helpful hints on designing a good survey.

Let's imagine we want to create a survey like this:

  1. Did you go to the clinic today? Yes/No

  2. Great! What doctor did you see?

  3. Why not? Clinic was closed/I felt fine/Clinic too far/Was busy

  4. Going to the clinic is important- please call 555-555 to reschedule your appointment.

We can add a bit more detail to make it easier to build. For each question you'll want to define:

  1. Question ID- how do you want the answer to the question to be tagged in the data export

  2. Label Text- the text that will be sent to the recipient

  3. Question Type- which of the question types above

  4. Options- if a multiple choice answer, what are the choices

  5. Display Condition- when do you want the message to be sent?

Below you can see one way of thinking about our survey:

Question ID

Label Text

Question Type


Display Condition

Question ID

Label Text

Question Type


Display Condition


Did you go to the clinic today?

Multiple Choice-Single Answer

Yes, No

Always show


Great! What doctor did you see?



If went_to_clinic = Yes


Why not? 


Clinic was closed, I felt fine,

Clinic too far, Was busy

If went_to_clinic = No


Going to the clinic is important.

Please call 555-5555 to reschedule your appointment.



If went_to_clinic = No

CommCare Messaging will automatically number options; for example, the question why_no_clinic will be sent out as:

Why not? 1. Clinic was closed, 2. I felt fine, 3. Clinic too far, 4. Was busy.

3. Build your survey

Use the Form Builder to add questions, options, and display conditions just as indicated in the Beginner Tutorial.

The survey described above would look like this:

It is important to keep things short! Specifically, when asking a multiple choice question you want to ensure that the text of the question, plus the text of all the possible answers fits in one message. If it is too long, it may be broken into multiple messages. Messages are not always assembled in the right order so it advisable not to have them break up.

There are certain words that cannot be used to test surveys. ex. SURVEY, START. 

4. Test your survey

Make sure to try out your survey before going live. You can give it a keyword (Setup SMS Keywords) and register yourself in the system (Configure a Mobile Worker for Messaging).

Using the keyword you can try out the survey multiple times. To test the survey using the keyboard, text the system using the format: #start keyword

When completing your survey keep in mind:

  • You can indicate a choice by replying with either the text of that choice or by simply putting the number of that choice (i.e. you can either reply with 2 or I felt fine. CommCare Messaging will ignore changes in spacing/capitalization, but not in spelling)

  • If your question is a Checkbox response you can reply with multiple numbers separated by a space. (i.e. in the example above you could indicate both Clinic too far and Was busy by replying: 3, 4)

If you reply with something that is not an acceptable reponse (i.e. there are 4 choices and you reply with "5") CommCare Messaging will send back a generic message that the response could not be understood, and that they should try again.

5. Schedule your survey

You can schedule your survey either using a Broadcast or Conditional Alert.

6. View your Data

Data from SMS Surveys are set-up in Forms. To review your SMS survey data, apart from other SMS data, you can go to the Form Exports in CommCare.

If you are looking for data from SMS users who are cases, be sure to select "unknown users" to export that information.