This feature is only available to CommCare users with a Standard Plan or higher. For more details, see the CommCare Software Plan page.
If you have a question that is not answered in the documentation, take it to Stack Exchange. This is a great place to have your question answered quickly!
Projects that use CommCare for service delivery or monitoring.
Projects that combine SMS with case management.
Data submissions that exceed the character limit (160 characters long)
SMS is not a sustainable solution at scale without a clear and dedicated budget.
SMS is preferred if messages are sent outbound to personal phones
SMS is preferred when Android devices are not available by all participants
SMS is preferred when limited data is collected on a regular basis, around 5-8 indicators
SMS is a good option if the users have very limited training time.
Messaging data can be reviewed on the Data tab. Use the SMS Export option.
Messaging data can be reviewed on the Reports tab. Use the Message Log to get insights into all of the messages sent or received in your project space.
Check out the SMS Reports page to learn more!
They are not that different. The Message Log can be downloaded to Excel too. The SMS Export is in the same format, but is more scalable for large projects
Yes. SMS reminders can be sent to e-mail.
There is no cost and no character limit to send reminders over e-mail.
Go to Message Content, and under the Send* dropdown select e-mail.
CommCare Messaging does not support USSD
USSD stands for Unstructured Supplementary Service Data.
Case properties can be
used as a trigger for an SMS reminder or survey.
loaded to set the send date, send time.
referenced inside message content.
These are some useful case properties
|contact_phone_number||sets the phone number that receives message. Always include the country code.|
|contact_phone_number_verified||required case property to activate two way messaging, set to equal 1.|
|time_zone||used to adjust the send time for a case|
|language_code||sets the default language code for a case (ex. en, fra)|
|partial_submission||meta data available in the form export. determines if a survey was complete|
To see the complete list check out Setting up Reminders
Use SMS best practices and include SMS hidden values inside of your CommCare forms.
Complex triggers can be calculated by using a hidden value that combines several questions into one output.
Yes. Submitting data through an SMS survey or Keyword can update case properties.
An updated case property can trigger a follow-up SMS reminder.
An update case property can be used to update a case list for a mobile worker.
No. SMS answers cannot directly trigger the submission of a secondary form.
For one off messages, a mobile worker can select a phone number from a case list and type a message using the native Android messaging app.
In CommCare, form submissions can update hidden values. The CommCare Messaging system processes case updates to see if they trigger a rule set up in the configuration.
CommCare does not support directly triggering SMS messages inside of a form.
There are ways to set random triggers in a form using advanced CommCare Functions.
The output of that function can be saved as a case property.
Web Users typically do not receive SMS messages. The same person can receive SMS messages if they are enrolled as a mobile worker.
A gateway is essential for international projects to support in-country messaging
To learn more check out Set-up an SMS Connection
Gateways act as a pass through. Delivery of SMS messages depends on the reliability of the local mobile operator.
Gateways cannot send messages if they are offline.
Gateways cannot guarantee that SMS messages are delivered on time.
Twilio gateways use phone numbers maintained by CommCareHQ to send messages inside the US and a limited number of international countries. The per message rates can be high based on the country destination.
To learn more check out Gateway Options for SMS Projects
CommCare HQ has established free Gateways in some countries. Today, we support gateways in Ethiopia, India, Lesotho, Mozambique, South Africa and Uganda.
In most cases, gateways cost money. The primary costs include:
Purchase of the smartphone,
Maintenance of a phone number or active SIM card
Assuring the gateway has sufficient credit
And may include subscription costs of the Gateway provider
Each message from CommCareHQ costs $.01/message.
If you have additional questions, reach out to email@example.com to learn more.
SMS Gateways are managed in the SMS Connectivity section of the Messaging Tab
Project staff are responsible for managing SMS gateways.
Project staff are best suited for this, especially if it requires monitoring and maintaining a phone numbers in the field.
Both Twilio and Telerivet integrate easily with CommCareHQ.
For international SMS projects, many projects use a separate Android phone to create a Telerivet gateway. This requires an active local SIM card.
For U.S. based SMS projects, many projects choose to use Twilio. A web based phone number can be purchased for $1/month.
If the messaging system is meant to deliver messages en masse at a specific time of day.
Telerivet Gateways have an SMS rate limit, of about 600 messages per hour.
Often projects will calculate the daily SMS rate limit, but should actually consider the peak number of messages per hour. The daily limit per Android gateway is 14400 messages a day.
For example, 6,000 cases are all set to receive an SMS survey message at 10h00. The rate limit works such that it would take 10 hours to send out messages in batches of 600 message per hour. The last of these cases would receive their survey message at 20h00.
The SMS rate limit does not depend on the paid Telerivet subscription.
The SMS rate limit can be increased by downloading Expansion Packs from the Google Play store. Each additional expansion pack raises the rate limit by 60 messages per hour. You can download up to 10 expansion packs.
One way to further increase the SMS rate limit, is to purchase an additional Android phone, and add a local SIM card.
CommCare Messaging supports splitting contacts between gateways.
Inbound SMS messages do not have rate limits
Outbound SMS message do have rate limits, based on the gateways capacity. Shortcodes do not have the same rate limits.
To test an SMS gateway, test each of the rules in your SMS system design.
The first priority is to confirm that messages are sent to phones, and incoming messages are received.
To pass gateway tests, there must be an active gateway phone and a working API connection.
To test an SMS gateway in multiple countries, procure a SIM card for each country mobile operator. Start by sending test messages to each phone. Once received, send in a response to confirm that messages can be sent both ways.
For more information regarding managing your SMS system check out the Telerivet FAQ for helpful tips.
Integer, respond with a number
Single-select, respond with a specific choice
Date based, set the date sequence for your project space
Not so good
Text questions are prone to error data entry errors, and hard to interpret
SMS Surveys require inbound messages. Support for inbound messages is limited to projects with a subscription that is PRO or higher.
SMS Surveys are not idea for collecting unstructured incoming messages
A contact cannot have more than one open survey at a time.
A contact cannot restart or overwrite submitted SMS surveys
Two way messaging with mobile workers requires a verification workflow to enable inbound messages, where each phone replies ‘123’ to establish the phone number in HQ.
Try creating a Keyword, that can trigger the form used for the SMS survey.
Timezones in HQ are set to UTC as a standard. Use the reminder calendar, to compare the time configured in the reminder to the planned delivery in the calendar.
If you re-activate a reminder your Index Day will reset to 0 for all the contacts who receive that reminder.
Do not reactivate a reminder if you have a long sequence of messages.
A multi-event reminder starts at Day 0. Each day thereafter increments by 1.
If your reminder is activated on Monday, Day 1 is a Tuesday, Day 2 is a Wednesday and so on.
To learn more check out Sending Multi-Event Reminders.
Phone number configuration issues
The contact_phone_number is incomplete
The contact_phone_number is missing a country code
The contact_phone_number is not verified. Complete verification workflow for mobile workers. For cases, save and update the case property.
Gateway goes offline
Gateway runs out of credit for sending messages
The SIM card is disconnected by the mobile operator for exceeding SMS volume thresholds.
SMS Reminders are not activated
Message Log: Start by reviewing the message log to review any test data.
Reminder Calendar: Check the reminder’s calendar to see the upcoming messages for your configuration. Select one of the calendar message recipients.
Contact: Review the case data of an active case and any relevant case properties
Reminders: Open up reminders, verify case properties that serve as triggers.
Testing SMS is difficult. Without close monitoring, SMS systems can fail silently. If you experience an error please reach out to firstname.lastname@example.org.
This cost is used to support our infrastructure to process all SMS tasks, from scheduling the reminder, to processing the sms, and handing it off to the gateway.
Take into account the standard cost per message.
Is the cost increased if messages are sent between local operators?
Is there a cost for local SIM cards or phone lines?
Consider the volume of messages
How many cases will be contacted?
How many messages will each contact receive?
What is the maximum volume of messages per hour?
How many Android smartphones are needed as gateways to support your SMS volume?
Will the project procure phones for the SMS related work?
Messaging costs vary based on the local mobile operator.
Budget for the standard CommCare HQ messaging rate $.01 per message.
To get a rough idea of the delivery costs, check out the Twilio Pricing Page.
Tip: Working directly with mobile operators can be a cost effective solution.
Yes. This is more frequent then you might expect, as phone ownership amongst women is not a guarantee.
CommCare Messaging supports one primary phone number. During case registration, the preferred phone number is set as the recipient. The field contact_phone_number is a case property and can be updated over time.