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 storing a single phone number in the case. For example, you won't be able to store both a mother and husband's phone number in the case.
The following properties need to be included in the case:
- contact_phone_number - This is the phone number to send messages to. It should include the country code (ex. 1 for the USA or 91 for India) and the rest of the phone number. It should not have any spaces, dashes or other punctuation. For example, both "12066181323" and "910981231234" are valid values. "1-206-617-1234" will not work.
- contact_phone_number_is_verified - This should be set to "1" to indicate that the phone number has been verified and is a real number.
- contact_backend_id - This specifies which SMS provider to use when sending SMSs to the number. Depending on the target phone number and carrier, this can be set to a number of different values.
- MOBILE_BACKEND_UNICEL - This should be used for any Indian projects.
- 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.
- 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.
- [optional] time_zone - This specifies the time zone of the phone number. If messages are sent to the case at a particular time, this time zone will be used. Otherwise, UTC will 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 Settings and Users -> Project Settings and viewing the list available for "Default Timezone".
- [optional] language_code - For an SMS survey available in multiple languages, this specifies which language to use when running the survey. This should match the language codes specified when defining the application on CommCareHQ. For example this would be set to "en" for English or "hin" for Hindi.
Basic Form Setup
In a form that creates or updates the case, you can do the following to quickly enable CommConnect.
- Add a question with an ID of contact_phone_number of type "Long Number". Its important that you use "Long Number" as an "Integer Number" cannot store enough digits for a phone number.
- Add a date node to the form with an ID of contact_phone_number_is_verified. You can set the calculate condition for this data node to evaluate to 1 if phone number was entered or 0 otherwise. Ex. if(/data/contact_phone_number != '', 1, 0)
- Add a data note to the form with an ID of contact_backend_id. Depending on your desired gateway, you can set its calculate condition to "MOBILE_BACKEND_UNICEL", "MOBILE_BACKEND_MACH" or "MOBILE_BACKEND_TROPO_US".
- Important: Make sure that the form creates or updates a case, and that these properties are stored in the case.
- All Phone Numbers Must Be Unique.
If a phone number is shared with another CommConnect-enabled case or verified or a mobile worker (even in another project), messages will not be sent. To address this issue, close at any other cases using that phone number or delete the verified number from the mobile worker.
- Verifying a Number
The example above automatically marks an added phone number as verified. Alternatively, you may have the health worker tries to call or text the user. Once this has been done successfully, they can use a form to set the value of contact_phone_number_is_verified to 1.