Register contacts for use in the system.  There are a number of options for doing this:

• Registering a Mobile Worker Contact 

• Registering a Case Contact

• Allow Contacts to Self Register (they can send an SMS to register themselves)

• Bulk Import Cases Using Excel

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: 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?"

Open

If the answer is Yes, capture the result in a question on the SMS survey with the value "1".

Open

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:

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:

1. In India, send a message to +919845204984. Due to government regulations, you cannot respond directly to the phone number which sends you messages. 

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

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:

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

1. Go to your project's SMS Settings page (Messaging -> General Settings). You must a be project admin in order to do this. 

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

Enable Self-Registration Over SMS for Mobile Workers

1. Go to your project's SMS Settings page (Messaging -> General Settings). You must a be project admin in order to do this. 

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

8. Select Confirm Import.  This will create all the contacts in the Excel document.