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! 

CommCare Messaging Frequently Asked Questions

SMS Basics

When should people use CommCare Messaging?

• Projects that use CommCare for service delivery or monitoring. 

• Projects that combine SMS with case management.

How can I see my messaging data?

• 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 https://dimagi.atlassian.net/wiki/x/Dorifw to learn more!

How is the SMS Export different from the Message Log?

• 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 

Can I send SMS reminders over e-mail? 

• 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.

Can CommCare Messaging work with USSD?

• CommCare Messaging does not support USSD

• USSD stands for Unstructured Supplementary Service Data.

• If your project requires USSD, consider using a system like Telerivet. Telerivet's USSD Expansion pack enables you to send USSD requests and receive replies via Telerivet, allowing you to check and recharge your phone's balance and interact with mobile banking services.

How do I specify a language for sending messages?

• If you have multiple languages in your project, check that all languages appear under the Languages page. To set the language for a mobile worker, use the mobile worker page. To set the language for a case, include the case property “language_code.” English = en, French = fra.

• To learn more check out https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143954640.

Case Management

How can I use case management in Messaging? 

• 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.

What case properties are useful to set-up a Messaging project?

• These are some useful case properties:

To see the complete list check out https://dimagi.atlassian.net/wiki/pages/resumedraft.action?draftId=2290778113&draftShareId=67b371a5-7deb-4e4d-8067-2d70159718e8.  

What is the best process for building complex messaging? 

• 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.

Can we dynamically trigger a workflow with SMS answers?

• 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.

How does CommCare support requests for in-app messaging?

• 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.

Can you set a case based triggers to arbitrary phone numbers or users (mobile and web)?

• 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.  

I have a conditional alert which is scheduled to send at 00:01 (midnight), but I don't remember choosing this time. Why is this?

The old way of configuring conditional messaging alerts allowed you to start an alert on a date stored within a case property and also send "Immediately". It might not have been obvious before, but the behavior in the old reminders framework for this type of configuration was to start the alert on the date from the case property and send at 12:01am, so this is the way the alert has always been behaving. The only difference now is that the user interface makes it much clearer what the actual configuration is. If this wasn't the time you wanted the alert to send, you can just update it to a new time.

I see "Interpret send times using GMT when recipient has no preferred time zone" enabled for some of my existing alerts, but I can't set it for new ones. What is this option?

Answer: The old reminders framework used GMT as the default time zone when interpreting send times if a contact didn't have a preferred time zone, so this is how the alert was always behaving. The new framework will use the project's time zone when interpreting send times if a contact doesn't have a preferred time zone, so this option is only shown for old alerts that started off on the old framework in order to preserve the same behavior as before. If you want the alert to interpret the send times in the project's time zone by default, then you can uncheck this option and any new events scheduled from the alert will use the project's time zone by default instead. If a contact has a preferred time zone, that will still be used over the project's time zone.

My alert is a "Custom Immediate" schedule type but I can't seem to add any events or change the times each event waits. Why is that?

Answer: The "Custom Immediate" schedule type is a custom schedule where the events are defined by waiting a certain number of minutes after the last event. This use case has caused some confusion, especially when used with a repeating schedule, so it's use is discouraged and support for this use case is limited. As a result, you can create new alerts of this type but there are some parts of it that will not be editable. You can still edit the message content that is sent, however. If you need a custom schedule type, consider using the Custom Daily schedule which is a much more robust custom schedule type and allows editing of events.

Gateways

When do I need to set up a gateway?

• A gateway is essential for international projects to support in-country messaging

• To learn more check out .

What common risks should I be aware of regarding gateways?

• 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.

How do the established gateways on HQ work?

• 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 .

Are gateways free?

• 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 support@dimagi.com to learn more.

Who manages SMS gateways?

• 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.

Does CommCare have a preferred Gateway provider? 

• 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.

• For India bases SMS projects, Unicel is preferred. Additionally, India has regulations involving SMS projects. More information can be found at .

What is the volume cut-off for a Telerivet gateway versus going to Telecoms?

• 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.

How do I manage the SMS sending rate limit? Does it depend on my Telerivet subscription level? 

• 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.

Is there a difference in Message Loads between inbound and outbound SMS? 

• 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.

How do you test an SMS gateway?

• 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.

How do you test a gateway in multiple countries?

• 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.

• For more information on testing gateways in India, please see .

SMS Surveys

What question types can I use to send out questions via SMS survey? 

• Good

  • 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

• Not supported

  • Images, multimedia

  • GPS

What are limitations for using SMS Surveys?

• 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

How flexible is two way messaging?

• 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.

How do you test that the SMS survey is setup correctly?

• Try creating a Keyword, that can trigger the form used for the SMS survey.

How do I test the send time of an 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.

SMS Reminders

How do I reference a case property in an sms reminder? 

• In the content section of the reminder set-up, you can reference a case property using the syntax {case.name} or {case.phone_number}.
  Follow the link to learn more about .

• Note: The case property must exist to be output in the SMS message.

• Note: It is important to use brackets { } and not parentheses. 

What happens when you re-activate a multi-event reminder?

• 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. 

What is the index day a multi-event reminder? 

• 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 .

QA and Troubleshooting

In what ways does CommCare Messaging most often break?

• 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

How do you test that the project messaging is set-up correctly?

• 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.

• For further testing messaging in India, please see .

Is testing SMS as difficult as it was a couple years ago?

• Testing SMS is difficult. Without close monitoring, SMS systems can fail silently. If you experience an error please reach out to support@dimagi.com.

SMS and Finance

Why does CommCare charge $.01 per SMS message?

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.

Do we have any messaging budget tools?

• 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?

How much does it cost to send messages internationally?

• 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.

• Note: Sending text messages between countries will be more expensive.

SMS Implementation 

Has anyone done an SMS project where the intended beneficiary did not have a phone but the husband did? 

• 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.

What is the best time of day to send reminder messages? 

• Before setting a send time, consult with recipients to understand their daily routines. 

• The best practices is to allow each contact to set a time that works for them. 

• If possible, allow the send time to be flexible so that users to change it over the life of the project.