Getting Started with Messaging
Don't forget to visit the CommCare Messaging Home Page.
Overview
CommCare allows you to schedule SMS messages, emails or IVR (voice calls) to cases and mobile workers registered in the system. Here are some example usage cases:Â
Sending a reminder to a health worker when one of their beneficiaries is due for a delivery.
Sending counselling messages to beneficiaries (for example, reminding them to take their iron pills). Â
Sending a short survey to a beneficiary (for example, asking if they've attended a clinic)
Have a patient request information from the system. Â For example, if they are enrolled in a smoking cessation study, they may request support messages from the system.Â
Messaging allows you to setup keywords (so users can send messages and data to the system on their own), reminders (scheduled conditional messages to a specific phone number) and broadcasts (mass messages or surveys to group of numbers). Â
The SMS Basics section covers basic information about how SMS works and is priced in CommCareHQ. Â
If you have questions, check out CommCare Messaging Frequently Asked Questions.
SMS as a Medium
SMS, as a medium, is like email in that information is not encrypted before being sent. This means that you should not include personally identifiable or sensitive information in SMS, just as you would not in an email.Â
SMS is also not a medium that is 100% reliable. Messages can be dropped due to network issues and often there is no way for a sender to know if the recipient actually received the message. For this reason, SMS should not be used for situations such as reaching out for help in a life-threatening emergency, and other more reliable mediums should be used instead.
With all of this in mind, SMS does make a good medium for use cases such as generic SMS messaging campaigns, appointment reminders, or alerts.
How CommCare HQ Sends Messages
CommCareHQ uses an SMS Gateway to send and receive messages.  SMS gateways are phone numbers provided by other companies (or cell phone companies) that connect to the cell phone network to send and receive messages.  CommCareHQ is connected to multiple gateways to support different countries. Â
More information on Dimagi's existing gateways can be found https://dimagi.atlassian.net/wiki/x/rwfKfw.
Using an Android Gateway
If your country isn't supported by Dimagi's existing gateways you can use an Android-based phone to send and receive messages for your project.  This will use the phone's SIM card and SMS balance.  Dimagi has partnered with Telerivet to use their system to support Android gateways. The Android phone will connect to CommCareHQ using the internet to know when to send messages and to send incoming messages to CommCareHQ. Â
Android phones are typically used for low volume projects since cell phone companies usually limit the number of messages that can be sent or received through a regular phone number.
Sending an SMS directly from a phone
A CommCare phone application can also generate an SMS from a form using the phone's default SMS application and allow the user to send this message directly to the recipient, without requiring a server. This approach gives full control to the mobile user and does not require data connectivity between the user and the server. It can therefore be useful in settings where the cell network only supports SMS messages. SMS costs are charged to the user's SIM card and CommCare cannot send these messages automatically, always requiring direct user interaction. Here is a brief description of how to set up a CommCare form to generate an SMS.
Short Code vs. Long Codes
Depending on the gateway used, it can be a short code or a long code. Â Long codes are similar to regular phone numbers. Â Short codes are special phone numbers that have a specific name (ex. CommCare) or a shorter phone number and can be used to send a very high volume of messages. Â Short codes also allow for reverse billing. Â
Reverse Billing
When users send a message to your project's SMS gateway, they normally pay a per message cost - this is exactly like them sending a message to a friend. Since this cost can dissuade users from using your messaging system, some gateways are reverse billed. This means that users can send messages for free to the gateway, and you will pay for those messages instead of the user paying for them.
SMS Pricing
There are two types of costs associated with SMS - a monthly software plan cost for CommCareHQ and a per-message cost. Â
SMS Pricing Plan: To use SMS, you must be on the Standard or above software plan. The Standard plan allow for outgoing messages (messages from CommCareHQ to a user). To receive messages from users (example, users respond to surveys or send in information), you must be in the Advanced or above pricing plan.Â
Per Messages Costs:
If using a gateway integrated with CommCareHQ, your CommCare invoices will charge the per-SMS fee charged by the SMS gateway. The charge from the SMS Gateway can fluctuate and also depends on exchange rates as well as the destination number's country and network.
If using a Telerivet gateway, you may have to pay a monthly fee to Telerivet for use of their service based on your subscription, as well as pay for the cost of the phone, it's phone plan, and the cost of messages to and from the phone.
In all cases, your CommCare invoices will charge a USD 0.01 per SMS surcharge paid to Dimagi.
In all cases, large messages can be charged as multiple SMS. Typically, an SMS sent using only the Roman alphabet is charged as one SMS for each 160 characters (roughly), and an SMS sent using special characters is charged as one SMS for each 70 characters (roughly).
New In Country Gateways
For larger high-volume projects in countries we do not already support, Dimagi can support connecting a new gateway to CommCareHQ if your subscription allows it.  SMS gateways can be purchased directly from a cell phone company in a country, or from an aggregator that resells phone numbers. Setting up a new gateway requires a significant amount of time and can have high costs. After identifying potential providers, please use the Aggregator Evaluation Worksheet to ensure that key questions are asked and answered during meetings with respective telcos/aggregators. Once you have selected an appropriate gateway provider based on project requirements (cost, setup time, reverse billing), the gateway can be connected to CommCareHQ with assistance from Dimagi's developer team. Please contact information@dimagi.com for more information. Â
Messaging Best Practices and Use Cases
Below are some suggestions for how to effectively use CommCare Messaging / SMS in different use cases.
Setting Up Your Project for Messaging
Type of Messaging
When starting your project, you need to decide between outgoing-only and two-way messaging.  Check out the CommCare Messaging Vocabulary section to learn more.Â
Outgoing Only:Â Users can only receive messages and can't respond or send data to the system. Â (Available on the Standard Plan)
Two Way Messaging: Users can also send data back to the system by responding to surveys or sending in keywords. Â (Available on the Advanced Plan).
Choosing a Phone Number (SMS Connectivity)
To send and receive messages CommCare needs to use a phone number to send messages. Â This is also called a gateway. Â Depending on the country of your project, scale and type of messaging required, the following options are available:
Dimagi Owned Gateways : These are high scale phone numbers or shortcodes that are only available in certain countries. Â Per-message fees are lower and some countries support toll-free incoming messages for users.Â
Telerivet Android Phone: Send and receive messages using an Android phone by using the Telerivet app. This phone will connect to CommCareHQ and be used for messaging for the project. Â This option works well for smaller scale pilots. Â Project will directly pay costs for the phone and messages to and from the phone. Â
More details on SMS options are available here:Â Gateway Options for SMS Projects. Â Once you've chosen a gateway option, use for your project.Â
CommCare Messaging Vocabulary
This section contains definitions and links to key concepts in CommCare Messaging. Please click below to see!
Â
Â
SMS Basics
Sending an SMS to the Case
Send a welcome/confirmation message upon enrollment/registration
Why? Sending a message immediately upon registration is helpful because you can confirm that the phone number is correct and that the user is able to receive messages. It can also help in explaining how they are going to get messages.
How? Set up an offset-based reminder in which the reminder is triggered when a universal case property like name exists. Configure the offset to be 0 days, 00:01 time so that the message will be set 1 minute after registration the system, and set the repeat to 1 so that it only repeats one time.
Trigger: (For each case with:) case type ____; case property name (exists)
Start: Start date (as soon as it triggers); Start Offset 0
Send: Send (SMS); To (The Case); Frequency (Advanced); Schedule-type (Offset Based); Default Language __; Schedule- Days to Wait 0; Time to Wait 00:01; Language/Message __|Welcome! You are successfully registered!
Stop: Repeat the schedule (the following number of times:) 1
Keep your messages short (<160 characters)! If you send long messages (greater than 160 characters) your message will be broken up into multiple SMS that your phone will have to join together. This can make the message appear disjointed or even in the wrong order! Unfortunately Dimagi/CommCare cannot guarantee that long messages will be sent in the right order, or even the that they will get sent at all.  Also keep in mind that if you are doing a survey and have a label followed by a question, these will be combined into a single text message.
Allow your case to opt out if they want to. No one wants to be stuck receiving text messages you don't want. While hopefully you can do lots of testing and use SMS messaging best practices, some people may want to be able to remove themselves, or may need to be able to do so in accordance with IRB or other requirements. You can set up a simple keyword to do this. To do this, create a form that is a simple SMS survey and has an empty question/simple message and configure the form to deactivate any trigger or to close the case, whatever is appropriate for your project. Then set a keyword reminder like "stop" so that your clients can just text in "stop" in order to opt out.
Avoid Required Questions. In some cases users will not complete a survey.  Required questions in a survey will not allow that survey to be saved in a partial state. Make sure that questions are not marked as required.  For non-text questions, it is not possible to skip them through SMS anyway.