Messaging Beginner Tutorial
This tutorial will introduce you to using Messaging within your CommCare application. This will be based on a very simple application (registration of a pregnant woman and tracking of pregnant women.). We'll add some basic messaging to the application including a welcome message to registered women, a message to remind women to visit the clinic if she has danger signs and messages to health workers to remind them of delivery dates.
Reviewing CommCare and Case Management
Before starting this tutorial, please make sure you've completed the Beginner Tutorial and Basic Case Management Tutorial. This contains important information about setting up a basic CommCare application.
Learning Objectives for Messaging Beginnner Tutorial
In this tutorial you will learn the following:
Choosing the SMS connection for a project
Registering a case that has a phone number that can be used for Messaging
Adding a phone number to a mobile worker so that they can send and receive messages
Setup a Reminder that is sent to all cases
Setup a Conditional Reminder
Setup a Reminder That Sends Based on a Date in a Case
Viewing Messages in the Reminder Calendar and Message Log
Before starting this tutorial, setup a new project space, unless you've already done so.
Tutorial Contents:
Choose an SMS Connection for Project
All SMS projects require an SMS connection to send and receive messages from users. Dimagi provides a number of shared connections for use in projects. Details on Dimagi's connections are available on these pages:
This tutorial will use one of Dimagi's international SMS connections, Twilio. This connection supports sending messages to many countries, but at a higher cost. If there is a specific connection that makes more sense in your country, feel free to use that instead.
Choose Twilio Connection
Go the Messaging tab and choose the SMS Connectivity page.
From the list of gateways, find MOBILE_BACKEND_TWILIO and click on the Set as Default button. This will setup the project to use Twilio to send messages by default.
Register a Case For Messaging
This describes how to setup a form that will register a case for use with Messaging. You can currently only have one phone number per case. We need to save this phone number to a specially named case property called contact_phone_number.
Create and Setup a New Application
1. In your project create a new application called Pregnancy Messaging.
2. Update the first module to set the name to Pregnancy
3. And then set the case type to pregnancy.
Create the Registration Form
This tutorial assumes you already know how to create a form with hidden values. Rename the Untitled Form to Registration and add questions so that it resembles the following. Some important things to note:
We name the phone number question contact_phone_number. This is the name of the special case property that Messaging will look for when creating a new case. When entering a phone number here, it must include the country code. For example, for an US phone number you would enter 15551234567. For an Indian number you would enter a number like 919560196285.
We add a hidden value called contact_phone_number_is_verified with a calculation of 1. This is also needed as a case property for Messaging to know to send messages to a case.
The full definition of the form is listed below:
Question ID | Type | Label | Required | Validation | Calculate |
|---|---|---|---|---|---|
name | Text | Name | Yes |
|
|
edd | Date | Expected Date of Delivery | Yes | . > today() and (. - today() <= 275) |
|
contact_phone_number | Phone Number or Numerical ID | Phone Number |
|
|
|
contact_phone_number_is_verified | Hidden Value |
|
|
| 1 |
Save the form and configure the case management to create a new case. Save all the questions as case properties. Its important the contact_phone_number and contact_phone_number_is_verified case properties are named correctly.
This form is now setup to register a new case that is setup to send and receive SMS messages. We'll now configure an Update form that the mobile worker can use to identify high mothers with any risk symptoms.
Configure a Follow Up Form
We'll now add another form to the application to allow health workers to follow up with pregnant women.
1. Add another form to the Pregnancy module using the + Form link.
2. Name the new form Follow-Up.
3. Add questions and a hidden value to the form that will evaluate the mother for any risk symptoms.
The following calculations and display logic is used in the form:
Question ID or Choice Value | Type | Label | Required | Display Logic | Calculation |
|---|---|---|---|---|---|
danger_signs | Multiple Answer | Does the mother have any of these risk symptoms? |
|
|
|
rupture_or_leaking | Choice | Rupture or leaking |
|
|
|
continued_bleeding | Choice | Continued Bleeding |
|
|
|
severe_headache | Choice | Severe Headache |
|
|
|
convulsions | Choice | Convulsions |
|
|
|
visited_clinic_already | Single Answer | Has already visited clinic for symptoms? | Yes | /data/danger_signs != '' |
|
yes | Choice | Yes |
|
|
|
no | Choice | No |
|
|
|
clinic_visit_reminder | Label | Please check in with this mother weekly until she visits the clinic. |
| /data/send_clinic_visit_reminder = 'yes' |
|
send_clinic_visit_reminder | Hidden Value |
|
|
| if(/data/visited_clinic_already = "no", 'yes', 'no') |
4. Save the form and configure the case management for the form. This form will be setup to update or close cases. We'll only save send_clinic_visit_reminder to the case. When we setup the reminder, we'll use this case property to determine if a pregnant mother should receive a reminder to visit the clinic.
Our application is now setup with the information it needs to trigger sending reminders to cases. We now need to add phone number information to any mobile workers so that we can also send them messages.
Setup a Mobile Worker for Messaging
To setup a mobile worker for Messaging, we just need to add their phone number in the correct format. The phone number must be added with the country code. For example, for an US phone number you would enter 15551234567. For an Indian number you would enter a number like 919560196285. Register a new mobile worker (if needed) and set their phone number using the Add Number button.
Verifying a Phone Number
For some projects, you may need two-way messaging (or to allow the mobile worker to send messages to CommCareHQ). To do this, you need to verify your phone number which will associate that particular phone number with the mobile worker (and not allow it to be used by other mobile workers). This is not needed for this tutorial, but you may need it for another project.
Now that our application and mobile workers are setup, we can now configure the reminders to send messages to the pregnant women and mobile workers.
Welcome Message Reminder
We'll now configure a reminder that will be sent to every registered mother. This message will inform them that they maybe receiving messages and what they mean.
1. To setup a reminder, go to the Messaging tab, then in the left side bar choose Reminders. Then click on the + Add Reminder button.
2. We'll now configure when the reminder will be sent. Give the reminder a name (ex. Welcome Message) and scroll down the Start section.
Send for Case Type: This controls which case type will cause the reminder to send. Choose pregnancy from the dropdown list.
Send Reminder For: This can be used to choose which cases will cause the reminder to send. We want the welcome message to be sent to All Cases.
Day of Reminder and Time of Day: You can also control what day or date and what time the reminder will be sent. For this reminder, we want it to be sent Immediately.
3. The next step is to choose who will receive a reminder. There are a number of options (the case, the case's owner, or a specific mobile worker group), but for this reminder we just need to choose Case.
4. We can now specify the message content to send. Choose the SMS send option and provide the message to send. For this reminder, we can set the message to "You'll receive reminders and tips over the course of your pregnancy on this number."
5. This reminder doesn't need to Repeat and we don't need any of the advanced options, so we can just go ahead and choose Create Reminder button.
We'll now follow a similar process to setup our other two reminders for the tutorial. Instead of setting up a reminder to all cases, we'll instead setup a recurring reminder to high risk mothers until they've visited the clinic.
Conditional Reminders
We'll now setup a reminder that will only be sent to mothers who have been flagged by the CHW as needing to visit the clinic. This message will also be setup to repeat on a weekly basis until the CHW visits the mother and indicates that she no longer needs to visit the clinic.
1. Add another reminder to the project (go to the Messaging tab, then choose Reminders and then click on the + Reminder button).
2. We'll now configure which pregnant mothers will receive this reminder. Give the reminder a name (ex. High Risk Clinic Visit) then scroll to the Start Section.
Send for Case Type: We want to choose pregnancy from the list as this message will be sent to pregnant mothers.
Send Reminder For: This will control which cases receive the reminder. We want to choose Only Cases in the Following State. Then set the reminder to send when the case property send_clinic_visit_reminder equals yes
Day Of Reminder and Time of Day. This controls what day and time of day that the mother will begin to receive this reminder. For this example, let's assume that our clinic day occurs on Tuesdays. So we want to send the mother a reminder on Monday at 9am. For Day of Reminder choose Specific Day of the Week and Monday. This option will send the message on the next upcoming Monday after the pregnant mother is flagged for a clinic visit. For Time of Day choose at a Specific Time and 9:00.
The next step is to choose who will receive the reminder. We want this reminder to go to the case (the pregnant woman), so choose Case.
4. We can now specify the message content to send. Choose the SMS send option and provide the message to send. For this reminder, we can set the message to "Please visit the clinic for a checkup. Clinic is on Tuesday mornings."
5. We will also configure to reminder to Repeat every week until the mother visits the clinic. Choose the Indefinitely option and specify that the reminder should repeat every 7 days.
Concept
Reminders will automatically stop sending if condition used to start the reminder becomes false. In this case, if send_clinic_visit_reminder does not equal yes, the reminder will stop. You can also stop a reminder by using a stop condition, specified in Advanced Options.
6. Our reminder is now setup so we can go ahead and choose the Create Reminder button.
We'll now follow a similar process to setup our final reminder for the tutorial. This reminder will instead go to the health worker, indicating that the mother is due for delivery soon and she should be checked up on.
Date Based Reminder
The final reminder that we'll setup will go out to a different date for each client, based on their date of delivery. This reminder will also go to the health worker and remind them that a particular mother is due for delivery in the next few days.
1. Add another reminder to the project (go to the Messaging tab, then choose Reminders and then click on the + Reminder button).
2. We'll now configure which pregnant mothers will receive this reminder. Give the reminder a name (ex. Delivery Reminder) then scroll to the Start Section.
Send for Case Type: We want to choose pregnancy from the list as this message will be sent for pregnant mothers.
Send Reminder For: This will control which cases receive the reminder. We want to choose All Cases since all pregnant mothers will have this message sent out for them.
Day Of Reminder and Time of Day. This controls what day and time of day that the mother will begin to receive this reminder. We want to send this reminder 3 days before the expected delivery date at 9am. For Day of Reminder choose Date in Case. Specify the case property as edd and before date by 3 days. For Time of Day, choose Specific Time and enter 9:00.
3. The next step is to choose who will receive the reminder. We want this reminder to go to the health worker (the mobile worker), so choose Case Owner (this is the mobile worker who registered the case).
4. We can now specify the message content to send. Choose the SMS send option and provide the message to send. For this reminder, we can set the message to "Please visit {case.name}. She is due for delivery in 3 days". The special syntax {case.name} allows you to use case properties in the message. You can replace name with another case property if you want to have that in the message instead.
5. This reminder doesn't need to Repeat and we don't need any of the advanced options, so we can just go ahead and choose Create Reminder button.
Now that our reminders are all setup, we can use the application to register some test data and verify that the reminders are working correctly and are sent to each user.
Testing and Viewing Scheduled Reminders
Now that our reminders and application is setup, you can use a mobile worker to register a new pregnant mother and view her scheduled reminders on CommCareHQ.
Setup a Sample Case
Register a new mobile worker for your project and add a new phone number as described in the Setup a Mobile Worker for Messaging.
Install the application on a phone and register a new pregnant woman using the application. Make sure you enter a valid phone number (including country code) when registering the mother.
Fill out the Follow Up form and indicate that the woman has risk symptoms and hasn't visited the clinic yet.
Viewing Cases in the Calendar
Go to the Messaging tab and click on Reminder Calendar in the left bar. You'll see the each upcoming message scheduled to go out to cases and mobile workers. For repeating reminders, only the next scheduled reminder will be displayed.
Viewing Messages in the Log
The message log can be used to view a history of all messages sent for the project. To view the message log, go to the Reports tab and choose Message Log from the left bar. You can choose a date range and filter to specif messages by message type. If you leave Message Type blank, it will show all messages. Click on the Apply button to view the messages in your chosen date range.
Basic Troubleshooting
If your messages are not in the message log, there is some basic troubleshooting that you can do.
Check the Error Log: Go to the Messaging tab and choose Reminders in Error on the left pane. This should show you a list of reminders that failed to send out. Review this list and address any issues notes.
Verify the Phone Number: You may have entered the phone number incorrectly - make sure you've included the country code when entering the number for the case or phone. You can also send test message. Go to the Messaging tab and choose Compose SMS. Type the phone number here and a message and choose Send.
Upcoming Messages not in Calendar: If the upcoming messages are not in your reminder calendar, then you may have not configured your reminder correctly. Use the Case List report to make sure the registered cases have the right set of case properties (and match your reminders).
Other troubleshooting tips are available here: .
Congratulations, you've completed the messaging beginner tutorial! See to read more about messaging and other functionality.