Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Overview

Info
titleSpecial Note about SMS in India

In order to send SMS to an Indian number, that number may need to opt-in to receive SMS. It's a best practice to have each Indian number you want to send sms to follow the opt-in process. Details can be found here: SMS In India

To send a phone number to a case (ex. to a pregnant mother), the phone number and some additional details need to be stored in the case. At the moment, CommConnect only supports a single phone number in the case. For example, while you may be able to store both both a mother and husband's phone number in the case, only one of the two will be supported for CommConnect. 

The following properties need to be included in the case:

...

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.

Info
titleImportant

Make sure you understand Case Management well before continuing.

Case Properties

Below are the case properties to set on a case in order to enable it for messaging:

Case PropertyRequiredDescription
contact_phone_numberRequired for one-way SMSThis 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.

...

contact_phone_number_is_verified

...

Required for two-way SMSSet this to the value 1 if you want this contact to be able to use two-way SMS (that is, to send replies to the system). Only one contact can hold a number for two-way SMS so if another contact has registered the same number for two-way SMS, the contact who registers it first will own it for two-way.
commcare_email_addressRequired for emailSet this to the contact's email address to send email content to them.
time_zoneOptionalThis 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

...

OptionalIf you translate the messages in your alerts, you can set the contact's preferred language here. This value should match the language codes

...

title[Advanced] Contact Back End

...

that you define on the SMS Languages page.
contact_backend_id

...

Depending on the target phone number and carrier, this can be set to a number of different values shown below.  If this case property is omitted or left blank, one of the providers below will be automatically chosen when sending sms to the case based on the phone number's country code.

  1. MOBILE_BACKEND_UNICEL - This should be used for any Indian projects.
  2. MOBILE_BACKEND_MACH - This offers outgoing messages to many countries but does not support incoming messages.  This provider will not work well for interactive SMS surveys.
  3. MOBILE_BACKEND_TROPO_US - This is a US based phone number. Unless you are based in N. America, messages to and from this provider are going to be more expensive. 
  4. MOBILE_BACKEND_TROPO_CANADIAN - This is a Canadian-based phone number.  It typically has better international reach than the US number.

Basic Form Setup

In a form that creates or updates the case, you can do the following to quickly enable CommConnect.  

...

Notes

...

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


Errors

If you happen to run into errors during the registration and testing of SMS messages, you can review our error message descriptions here.