...

...

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. 

...

...

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.  

...

...

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

Please note, for the India Unicel gateway, the user will need to opt into messages from Dimagi. Please see this help page for more information.

...

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)

1. SMS Gotchas

MACH sometimes changes the sender ID (or the phone number the recipient sees as the source of the SMS)

...

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. Honduras specifically  has regulations in place that limits an bulk messaging within the country.  

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?

...

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

...

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?

...

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

Who manages SMS gateways?

...

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

...

SMS

...

SMS Reminders

How do I reference a case property in an sms 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.

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.

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

...

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.

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 Pricing

For any SMS pricing questions, please refer to https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143950358/CommCare+Pricing+FAQs#Fees-for-SMS