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.
   
   

   Open

   

   
   
   
   

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.
   
   
   

   Open

   

   
   
   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 the Telerivet setup page 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).