...
| Info | ||
|---|---|---|
| ||
Make sure you understand Case Management well before continuing. |
| Warning | ||
|---|---|---|
| ||
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
For SMS Messaging in the United States, you are required to confirm with the end user whether they opt into receiving messaging or not. You can capture this consent in the backend as a case property to initiate messaging.
To do this, begin all SMS messaging workflows with 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 Required 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 | .contact_phone_number_is_verified | Required for two-way SMS | Set 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_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. |
Errors
If you happen to run into errors during the registration and testing of SMS messages, you can review our error message descriptions here.