...
| hidden | true |
|---|
...
To send and receive SMS in CommCare, you need to set
...
up an SMS connection with a supported gateway. This involves selecting an SMS provider, configuring the gateway in CommCare HQ, and linking it to your project. A properly configured SMS connection ensures reliable message delivery for reminders, surveys, and alerts.
| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Setting up CommCare Messaging lets you communicate with beneficiaries through automated SMS, email, or other messaging services. It helps with reminders, participant engagement, and valuable data collection. By linking your CommCare app to a messaging service, you can create efficient workflows for your program.
...
Below is a diagram showing the components needed for a CommCare Messaging integration.
...
This guide will walk you through the steps needed to set up and configure the CommCare Messaging feature for your project.
Step 1: Configuring a CommCare Application for Messaging
To use CommCare Messaging, your app needs to be set up correctly. Follow these steps (shown in video) to integrate the Messaging feature into your CommCare app:
Start by selecting the app you want to use for the CommCare Messaging integration. It can be either an existing app or a new app that you create from scratch.
Go to the Registration form and add "contact_phone_number" as a specific question to collect the phone number of the case/beneficiary. This is the case property that Messaging will look for when creating a new case. When entering a phone number, make sure to include the country code. For example, for a South African number, enter 2779 649 8782. This case property should be saved to the case for any case that will receive an SMS.
Create a hidden value named exactly "contact_phone_number_is_verified" and set it to “1” in the calculation condition. This indicates that the phone number is verified, and it's required for Messaging to know when to send messages to a case.
You can also create additional questions that will be used as SMS triggers for condictional alerts in the future, such as age, favorite color, etc.
Finally, save all these questions to case properties using app’s case managment. These case properties will be used as part of the integration. (If you do not save these questions to the case property, message integration will fail)
...
Important Fields to Note:
Field | Description |
|---|---|
contact_phone_number |
|
contact_phone_number_is_verified | We add a hidden value called contact_phone_number_is_verified with a calculation of 1. This is also needed as a case property for Messaging to know to send messages to a case. |
gender, are_you_pregnant | These are case properties that will be used as SMS triggers in this example for a conditional alert. |
Step 2: Setting up an SMS connection
Once your SMS system is designed and built, you will need to set it up to make it go live. This includes setting up your gateway, as well as connecting it to CommCare.
SMSes are sent through a Gateway. An SMS Gateway enables a computer to send and receive SMS text messages to and from an SMS capable device over the global telecommunications network (normally to a mobile phone). The SMS Gateway translates the message sent, and makes it compatible for delivery over the network to be able to reach the recipient. Dimagi provides a list of default Gateways based on already existing relationships with the providers.
CommCare provides a configurable Messaging system for sending SMS. To enable it in a particular location, you must establish an SMS gateway that provides SMS in your target region.
You can read more about your gateway options here:Gateway Options for SMS Projects
Step 2: Connect your Gateway in CommCare
Set a Project Gateway Connection
Go to the Messaging tab, select Dashboard and then select SMS Connectivity in the left menu.
...
Choose a gateway as the default. If needed, add another gateway (HTTP or Android).
Add Another Connection
If you'd like to use a different connection for your project, you can add it using the "Add Another Gateway" option at the bottom of the page.
...
Choose Telerivet (Android) to setup an Android phone based connection (https://dimagi.atlassian.net/wiki/x/zBnKfw).
...
When selecting a Gateway, consider the following items during your decision making:
Check which Gateways services the country you’re working in
Does the Gateway accept two-way Messaging? (In the event that the workflow requires two-way messaging)
Are there any Country regulations (Indian government has regulations preventing 2-way SMS)
What are the per message costs?
If using a global Gateway such as Twilio consider the exchange rate in the cost estimation as well
If you are choosing Telerivet (Android) to setup an Android phone based connection, you can read more about it here - https://dimagi.atlassian.net/wiki/x/zBnKfw.
You can read more about key considerations to be made while setting up Android Gateway (Telerivet) here - Key Considerations while Setting up an Android Gateway (Telerivet)
Once you have selected the gateway, mark it as default in the SMS Connectivity page as shown below.
...
Step 3: Setting Up the CommCare Messaging Schedule
This step connects the application we built in Step 1 to its conditional alert configuration. Follow the steps below and watch the video for guidance.
...
Messaging Configuration:
Ensure all required case properties for conditional alerts are saved in the case management section of the application.
Click the Messaging button on the top bar of CommCare HQ and select Conditional Alerts.
A Conditional Alert is triggered when a case property meets a specific condition. For example, an SMS or email will be sent when the case property are_you_pregnant is set to "yes" and the case_type is "sms_workflow," in the application we created in step 1, as shown in the video.
Setting up the Conditional Alert
Basic Information:
Enter a name for your conditional alert under the Basic Information tab and click Continue.
Rule Criteria
Choose whether all criteria must be met (useful when multiple conditions apply) or if any criteria can trigger the alert.
Select the case type as ‘sms_workflow’ and set the condition are_you_pregnant = "yes".
Click Continue to proceed to the Schedule and Recipients tab.
Schedule & Recipients Settings
The Status field determines whether the alert is active.
The Send field defines when the message will be sent, with the following options:
Immediately: Sends the message once as soon as the condition is met.
Daily: Sends messages on selected days at specific times.
Weekly: Similar to daily scheduling, but allows selecting specific days of the week.
Monthly: Similar to daily scheduling, but allows selecting specific days of the month. You can also choose options like the last day, second-to-last day, or third-to-last day of the month.
Custom Daily: Allows flexible scheduling, such as sending multiple messages on the same day or on irregular days (e.g., days 1, 2, 3, and 8 in a 14-day cycle).
Custom Immediate: Sends messages at custom intervals, with the first message sent a set number of minutes after the condition is met.
Example: Selecting "Immediately" means the message will be sent as soon as the ‘are_you_pregnant’ case property is set to "yes".
Recipient Selection: In the Recipients field, specify who will receive the message. If the recipient is the case, the application must create the contact_phone_number and contact_phone_number_is_verified case properties, as shown in the video.
Available recipient options:
The Case: The case that meets the criteria will receive the message.
The Case’s Owner: The owner of the case (e.g., a user group or organization).
The Case’s Parent Case: The parent case of the matching case will receive the message.
User Specified via Case Property: A CommCare user whose username is stored in a case property. The user must be a mobile worker in the same project space.
Email Specified via Case Property: An email address stored in a case property (only for email alerts).
Content Selection: Define the message content in the Content field. You can send:
SMS: A one-way message.
SMS Survey: A two-way message where the system collects responses from the recipient. Each question counts as one SMS.
Email: Sends an email instead of an SMS.
Custom SMS: A personalized message using case properties (e.g., “Hi [Name], your next appointment is on [Date]”).
This setup ensures that messages are sent to the right recipients at the right time with the correct content.