Register contacts for use in the system. There are a number of options for doing this:
Allow Contacts to Self Register (they can send an SMS to register themselves)
Registering a Case Contact
In addition to registering users as messaging contacts, you can also register a case as a messaging contact. This can be useful when you have beneficiaries you are registering and you want to send them messages.
Important
Make sure you understand Case Management well before continuing.
Opt-In Workflows Are Required
As of November 2023, Opt-In Workflows are required for SMS messaging in the United States. Please carefully read the information below to set up Opt-In Workflows.
Important: Required Opt-In Consent for SMS Messaging During Case Registration
For SMS Messaging in the United States, you are required to confirm with the end user whether they opt into receiving messaging or not during Case Registration. You can capture this consent in the backend as a case property to initiate messaging.
To do this, include in all SMS messaging registration forms a consent question such as "Do you consent to receiving SMS messaging?"
If the answer is Yes, capture the result in a question on the SMS survey with the value "1".
Then, set this value as a case property on the case named "contact_phone_number_is_verified".
If you have not performed this step, we will not allow SMS Messaging to go through.
This consent can be captured via an SMS survey or by receiving verbal confirmation during case registration via a frontline worker.
Additional Case Properties
Below are the additional case properties to set on a case in order to enable it for messaging:
Case Property | Required | Description |
|---|---|---|
contact_phone_number | Required for one-way SMS | This is the phone number to send messages to. It should be in international e.164 format, which generally means it should have the country code first (e.g., 1 for the USA or 91 for India) and then the rest of the phone number. Depending on the country, you may need to remove the leading zero from the national number before prepending the country code. It should not have any spaces, dashes or other punctuation. For example, both "15551234567" and "919812345678" are valid values. |
name | Required for SMS survey | This is the name of the case, excluding it when setting up a case may cause errors when sending an SMS to a case. |
commcare_email_address | Required for email | Set this to the contact's email address to send email content to them. |
time_zone | Optional | This specifies the time zone of the contact. If messages are sent to this case at a specific time, this time zone will be used to interpret those times. Otherwise, the project's time zone will be used. For example, to set US East Coast Time as the time zone, this should be set to "America/New_York". A full list of available time zones can be found by going to Project Settings and viewing the list available for "Default Timezone". |
language_code | Optional | If you translate the messages in your alerts, you can set the contact's preferred language here. This value should match the language codes that you define on the SMS Languages page. |
contact_backend_id | Optional | If you want to use a specific gateway for this contact and override any default gateway choosing behavior that the system would otherwise do, you can specify the name of that gateway here. |
Opt-Out Keywords
All end users are able to opt-out of messaging by replying "STOP" to any CommCare messaging. This cannot be modified or disabled.
Errors
If you happen to run into errors during the registration and testing of SMS messages, you can review our error message descriptions at https://dimagi.atlassian.net/wiki/x/Ti-Kfw.
Configure a Mobile Worker for Messaging
Follow these steps to enable Messaging for a mobile worker. For each mobile worker, we need to verify that the entered phone number is a real number. This verification occurs by sending a message to the worker's phone number and having them respond to that message.
1. Create or edit an existing mobile worker and go the page to configure that user.
2. Setup a phone number. Enter the phone number for the worker. It's important that the number is in international format (starting with the country code) and does not start with a plus. For example, a US number would be entered as "12068130912". Similarly, an Indian number would be entered as "919560187230". Click the "Add Number" button after entering the phone number.
For Indian numbers, please see the notes in the troubleshooting section below about opting into messages from Dimagi.
At this point, you have created a one-way phone number. This means that you can send outbound messages to this user using this phone number, and if that is all you require you do not need to continue with the rest of the steps. However, if you require the use of inbound SMS (that is, for this contact to send message replies to the system), then you will need to verify this phone number as described below.
3. A "Verify" button should appear next to the phone number. Click on this button to trigger sending a message.
4. A "Verification pending" message should appear underneath the phone number. You can still click the "Verify" button again to send another SMS.
5.. The user should receive a message on their phone asking them to respond with a "123". Depending on their country, they can either directly reply to the message or they may have to respond to a different phone number. For example, in India, the message will include the phone number to respond to. (See troubleshooting and notes below).
6.. One the system receives a message, refreshing the mobile worker page will show the phone number as "Verified."
Troubleshooting and Notes
1.. I see an "Already In Use" message and I can't click the "Verify" button.
This means that the phone number is already in use somewhere else in CommCareHQ. This could be in the same project or in another project. Unfortunately, Messaging only support a phone number being used once in the system. You'll need to delete the verified phone number from any other mobile workers (potentially in another project) and close any Messaging-enabled cases that use that phone number.
2. I don't receive a verification message on my phone
Depending on your country and carrier, we may not support sending messages to the entered phone number.
In India specifically, your number may be registered on a Do-Not-Disturb (DND) list. Before receiving any message from Dimagi, you'll need to opt-in to receiving messages from us. Send the message "START" to +917760962755. Once this is done, you can click the "Verify" button again to send another message.
3. My response is not received (or I can't respond to the message I get).
Depending on which country you're in, you may not be able to respond to the confirmation message that you receive. We're still working on our SMS coverage and what is available depends on the country (and potentially the carrier you're using).
If you are using a Telerivet gateway and you can't respond to the message you receive, then the connection is not configured properly. Double-check https://dimagi.atlassian.net/wiki/x/zBnKfw to make sure that you configured everything properly in CommCareHQ and in Telerivet.
If you are not using a Telerivet gateway and you can't respond to the message you receive, you could try sending "123" to one of the following numbers:
In India, send a message to +919845204984. Due to government regulations, you cannot respond directly to the phone number which sends you messages.
In other countries, the system we use to send outgoing messages may not support incoming messages. To get around this issue, you can directly send a message to our US incoming SMS phone number (+1 617 575 2704). Note: Sending a message to this number may incur international messaging fees. This should only be used for initially verifying the phone number (and not for interactive SMS surveys).
Special Note about SMS in India
In order to send SMS/IVR to an Indian number, that number may need to opt-in to receive SMS/IVR. It's a best practice to have each Indian number you want to send an SMS to follow the opt-in process. Details can be found here: SMS and IVR in India
SMS Self Registration
Overview
Users must be registered in CommCare before they can receive reminders or SMS surveys. Users can be registered in a variety of ways (a web-based application, in bulk through Excel (https://dimagi.atlassian.net/wiki/x/tCbKfw). They can also register themselves using SMS.
To self-register, the person must send the following message, replacing <projectname> with the name of your CommCareHQ project. The message to send also depends on whether the person is registering to become a case or a mobile worker:
Case Registration over SMS:
join <projectname>
Mobile Worker Registration over SMS:
join <projectname> worker <username>
This message is sent to one of the SMS gateways supported by the project (see https://dimagi.atlassian.net/wiki/x/fCnKfw). Also, when registering cases, it's highly recommended that a follow-up survey is sent to capture additional information to identify the case (name, etc.). When registering users, if the optional <username> is omitted, the name of the mobile worker will be the same as its phone number.
Enable Self-Registration Over SMS for Cases
Go to your project's SMS Settings page (Messaging -> General Settings). You must a be project admin in order to do this.
To enable case registration over SMS, enable the "Case Self-Registration" option. The following information needs to be provided:
Default Case Type: This is the case type that will be assigned to the newly created case.
Default Case Owner: This is the mobile worker or group that will own this newly registered case. In some situations, you may need to create a dummy mobile worker for these directly registered cases.
Registration Submitter: This is the mobile worker that is specified as submitting the registration. The majority of the time, this is a same as the registration owner.
The above configuration will create a participant case owned by the user gc if a case registration message is sent to one of the SMS gateways configured for the project. Once this is done, its is recommended that additional information is captured about that person by sending a welcome survey.
Enable Self-Registration Over SMS for Mobile Workers
Go to your project's SMS Settings page (Messaging -> General Settings). You must a be project admin in order to do this.
To enable mobile worker registration over SMS, enable the "SMS Mobile Worker Registration" option:
Bulk Registration of Contacts
NOTE: This page describes how to bulk register contacts that are cases. To bulk register contacts that are mobile workers, see https://dimagi.atlassian.net/wiki/x/AIHgfw.
For certain projects, it makes sense to register all the participants in the system ahead of time. This can be done by uploading their information through an Excel file using the Excel Importer. Create an Excel file with the following information/headers:
Case Name: The name of the registered case (or some other way to quickly identify who the person is).
contact_phone_number: This is the phone number of the person. The phone number should include the country code and contain no spaces and not have a + symbol. Also, be sure to define this column as a Text column in Excel, otherwise the phone number may not import correctly. For example, a US number should be 12065551234. An Indian number would be 919560187280
contact_phone_number_is_verified: This should be set to 1 for every item. It specifies that the phone number for the person is correct.
commcare_email_address: This is optional, but can be specified if you prefer to email your mobile workers (instead of sending a message).
case id: A blank column needs to be added here. This is the ID of the item (but since these are new items, they have no ID).
Additional Data: If there is other information you want to add about the person (ex. gender, age, etc.) you can also include that as additional columns in the Excel file. sample_excel_contacts.xls
An example Excel file can be found here: sample_excel_contacts.xls
Uploading Contacts
1. Go to the Data tab, then select Import Cases from Excel.
2. Select the Excel file that you want to import. Make sure that "This file has column headers" is set to True and select Next.
3. Specify the case type for the upload. This should be used by the Surveys in your application (ex. your case type is contact). If you haven't setup an SMS Survey, see https://dimagi.atlassian.net/wiki/x/DirKfw.
4. Choose the Excel column as the Case ID and Corresponding case field as the case id column in your Excel document.
5. Make sure "Create new records if there is no matching case" is checked.
6. Select Next step.
7. The next page lets you map the columns in your Excel document to case properties.
a. Case Name, choose the existing "name" case property
b. For contact_phone_number, check off "Create a new property instead" and type in and contact_phone_number
c. Follow the same step for contact_phone_number_is_verified and any other case properties.
.png?version=1&modificationDate=1713925462533&cacheVersion=1&api=v2&width=760&height=294)
8. Select Confirm Import. This will create all the contacts in the Excel document.