Send CommCare Install Info over SMS

This feature is only available on CommCare version 2.44.4 and below. It is not supported in the current CommCare version available in the Play Store.

Overview

Purpose: Use this API to facilitate the reinstallation of CommCare on the phones of already-registered users. All recipients should be on an Android phone. The users will receive two SMS: one with a link to the Google Play store to download and install CommCare, and one with the CommCare app install information which is used by CommCare internally.

Project Prerequisites: Your project must have a PRO plan or higher to use this feature, and you must enable "SMS Mobile Worker Registration" on the Messaging -> General Settings page.

Authentication: For more information, please review https://dimagi.atlassian.net/wiki/x/LwXKfw.

URL: https://www.commcarehq.org/a/[domain]/api/[version]/sms_user_registration_reinstall/

Available since: v0_5

Method: POST

Input and Output Structure

Input Parameters:

Name	Type	Required	Description	Example

Name	Type	Required	Description	Example
app_id	string	Yes	The unique identifier used by CommCareHQ to identify the app that will be installed on the user's phone	"abcd1234abcd1234"
users	list of json objects	Yes	A list of json objects representing the users to send the SMS information to. See below for the structure of each of these json objects.	{"phone_number": "16175551234"}
reinstall_message	string	No	A custom SMS message that will be sent instead of the system's default message, containing the link to the Google Play store for the CommCare installation. Be sure to leave a placeholder ("{}") for the link to the Google Play store.	"Click here to install CommCare: {}"

with each json object in the users list having this structure:

Name	Type	Required	Description	Example

Name	Type	Required	Description	Example
phone_number	string	Yes	The user's phone number, in E.164 format	16175551234

Output Structure:

Name	Type	Description	Example

Name	Type	Description	Example
success_numbers	list of string	List of phone numbers representing the users that were successfully processed.	["16175551234"]
invalid_format_numbers	list of string	List of phone numbers that could not be processed because they were in an invalid format.	["1617JKL1234"]
error_numbers	list of string	List of phone numbers that could not be processed due to error.	["16175551234"]

Sample Usage

Sample input (simple):

{
  "app_id": "abcd1234abcd1234",
  "users": [
    {"phone_number": "16175551234"}
  ]
}

Sample output:

{
  "success_numbers": ["16175551234"],
  "invalid_format_numbers": [],
  "error_numbers": []
}