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! 

General Troubleshooting

There are a number of reasons that a message may not be sent out from Messaging.  Please follow these steps to troubleshoot your application. 

Select a Default Gateway

Please make sure you've selected a default gateway for your project (Gateway Options for SMS Projects).  To choose a gateway, please go to Messaging -> SMS Connectivity.  More details can be found on Setup SMS Connection for Project. 

Open

Make Sure Your Phone Number is Supported by your Gateway

Go to the Compose SMS Message page (Messaging -> Compose SMS Message).  Type in the phone number you're testing with including a + symbol and the country code.  For example, for Canada enter +19051235555 or for India enter +919560187812.  Enter a test message and press the Send Message button.  Verify that the message appears on your phone.   You can also check the Message Log report by going to Messaging -> Message Log.  

If the message is not received by your phone, your selected gateway may not be supported by the project.  Please try a different gateway or contact Dimagi Support.  

Open

Check the Scheduled Messaging Events report

Make sure the reminder is appearing in Scheduled Messaging Events report.  If the reminder does not appear, that means it hasn't been setup correctly.

Check the Messaging History Report

Check the Messaging History Report. This will list all events that the system tried to process and whether they succeeded or had an error.

Mobile Worker Message

If the message is intended from a mobile worker, please ensure that the mobile worker is properly setup for (Configure a Mobile Worker for Messaging).  Make sure the phone number is in the correct format (includes the country code and phone number.  For example, 19058131234 will work for a Canadian number or 919560187612 for an Indian number).

Case - Ensure Correct Phone Number & Case Name

Please ensure that the case is properly setup for CommCare Messaging (Registering a Case Contact).  Make sure that your case has the case property contact_phone_number  and the case property name (name should not be null)

Bulk Messaging Regulations

Please note, for  Telerivet gateway it's important to check the country's regulations which might limit the amount of messages being sent at a time if sending bulk messages.

CommCare Messaging Frequently Asked Questions

SMS Pricing

For any SMS pricing questions in general, please refer to CommCare Subscriptions & Pricing FAQs | Fees for SMS

I’m using 2-way SMS to send surveys to my program participants. Will they be charged for SMSes?

Yes. When using either the pre-configured gateways that CommCare has, or when using your own Android gateway set up with Telerivet, when responding to SMS surveys, clients will incur normal messaging fees as outlined by thier mobile provider. This is something that the project team should consider when deciding whether or not to use 2-way messaging. Note: some projects who use 2-way SMS offer their project participants vouchers or phone credit as a part of their participation in the project to help off set this cost to the participant.

I don’t want my participants to incur messaging fees. Can we have a toll-free gateway?

CommCare does not have any pre-configured toll-free gateways. In order to set up a toll-free SMS gateway, an organization would have to connect their own Commercial SMS Gateways. This would require the organization to:

1. contract with a local telecom or aggregator who sets up the toll-free short code and gateway

2. contract with a CommCare Provider or other technical provider to connect the toll-free gateway to CommCare

This is a complex process both technically and contractually, especially in countries with multiple telecom providers. It is important to note that a toll-free gateway only applies to the telecom provider with which it is established. If a participant uses a different provider, their messages will not be toll-free.

Due to these challenges, many partners using CommCare choose alternative approaches to offset SMS costs for participants. These include reimbursing fees through phone credit vouchers, additional cash in distributions, or other means.

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

SMS Basics

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 Messaging Translations.

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:

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.

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

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