Sending an SMS directly from a CommCare form

Owned by Derek Hans
Last updated: Apr 03, 2024 by Krinda Wernicke
2 min read

CommCare can generate SMS messages 

  • From the server

  • Directly from the user's phone

Each option has distinct advantages and disadvantages. For a full discussion of server-based SMS messages, see https://dimagi.atlassian.net/wiki/x/XCrKfw. The server-based functionality provides automated messages without requiring user interaction, has a rich feature set for scheduling messages and selecting who receives a message and automatically bills the costs of the messages to the project. However, before a user action can trigger and schedule a message, the user needs to have data connectivity and successfully sync with the server.

Occasionally, a user may have cell reception and therefore can send an SMS directly but does not have data connectivity. Furthermore, users may want to customize a message and have the same functionality as they are used to experience with their phone's default SMS application. In these situations, CommCareODK can automatically pre-populate a new SMS using Android's default SMS application with a list of recipients and message content. The user then simply needs to click "send." The SMS cost is charged to the user's SIM card, as any regular SMS would be, and the SMS appears in the user's message history.  

This experience can be implemented using the Android app callout functionality.

  1. Create a hidden variable named sms_message. Populate it with the text string that should appear in the message body. 

  2. Create a hidden variable named sms_addresses. Populate it with the comma-separated list of phone numbers of the intended recipients.

  3. Insert the SMS-message sending question using the following steps:

    1. Insert an Android App Callout question, by going to Add Question > Advanced > Android App Callout.

    2. Open the form's XForms XML file, by going to the Form Builder Menu > Edit Source XML.

    3. Search for: 'odkx:intent' to find the instance of the Android App Callout question that you added above.

    4. Delete what is there, and replace it to match the example below. The "button-label" and the "data" attributes in particular for the "odkx:intent" element currently can only be set in XML.

    5. Update each of the following variables with content that matches what you would like to use:

      1. "Send SMS" => Change this to the label you would like to see on the SMS Button

      2. /data/sms_addresses => Change this to the full path of the hidden variable that contains a comma-separated list of phone numbers

      3. /data/sms_message => Change this to the full path of the hidden variable that contains the content of the message being sent

XForms
<odkx:intent xmlns:odkx="http://opendatakit.org/xforms" id="send_sms" class="android.intent.action.SENDTO" button-label="Send SMS" data="cc:xpath_key:concat('smsto:', /data/sms_addresses)"> <extra key="sms_body" ref="/data/sms_message" /> </odkx:intent>

Once deployed on an Android phone, the question should display a button labelled "Send SMS". Clicking the button will launch the phone's default SMS application with a new pre-populated message.