Versions Compared


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

This page will explain some basic concepts of SMS Messaging in CommCareHQ. 

SMS as a Medium

SMS, as a medium, is like email in that information is not encrypted before being sent. This means that you should not include personally identifiable or sensitive information in SMS, just as you would not in an email. 

SMS is also not a medium that is 100% reliable. Messages can be dropped due to network issues and often there is no way for a sender to know if the recipient actually received the message. For this reason, SMS should not be used for situations such as reaching out for help in a life-threatening emergency, and other more reliable mediums should be used instead.

With all of this in mind, SMS does make a good medium for use cases such as generic SMS messaging campaigns, appointment reminders, or alerts.

How CommCare HQ Sends Messages

CommCareHQ uses an SMS Gateway to send and receive messages.   This is a system  SMS gateways are phone numbers provided by other companies (or cell phone companies) that connects connect to the cell phone network to send and receive messages.   CommCareHQ is connected to different multiple gateways to support different countries.  


Android phones are typically used for low volume projects since cell phone companies usually limit the number of messages that can be sent or received through a regular phone number.

Sending an SMS directly from a phone

A CommCare phone application can also generate an SMS from a form using the phone's default SMS application and allow the user to send this message directly to the recipient, without requiring a server. This approach gives full control to the mobile user and does not require data connectivity between the user and the server. It can therefore be useful in settings where the cell network only supports SMS messages. SMS costs are charged to the user's SIM card and CommCare cannot send these messages automatically, always requiring direct user interaction. Here is a brief description of how to set up a CommCare form to generate an SMS.

Short Code vs. Long Codes


When users send a message to your project's SMS gateway, they normally pay a per message cost - this is exactly like them sending a message to a friend.  Since this cost can dissuade users from using your messaging system, some gateways are reverse billed.  This means that users can send messages for free to the gateway, but and you (the gateway) will pay for those messages instead of the user paying for them.  

SMS Pricing

There are two types of costs associated with SMS - a monthly software plan cost for CommCareHQ and a per-message cost.  

  • SMS Pricing Plan: To use SMS, you must be on the Standard or above software plan.     The Standard plan allow for outgoing messages (messages from CommCareHQ to a user).  To receive messages from users (example, users respond to surveys or send in information), you must be in the Pro or above pricing plan. 
  • Per Messages Costs: 
    • If using a
    • gateway
    , Dimagi
    • integrated with CommCareHQ, your CommCare invoices will charge
    a message . This fee differs based depending on which gateway you're using.     For Android gateways, you typically
    • charged by the SMS gateway. The charge from the SMS Gateway can fluctuate and also depends on exchange rates as well as the destination number's country and network.
    • If using a Telerivet gateway, you may have to pay a monthly fee to Telerivet for use of their
    application and
    • service
    , and then
    • based on your subscription, as well as pay for the cost of the phone, it's phone plan, and the cost of messages to and from the phone.
    • In all cases, your CommCare invoices will charge a USD 0.01 per SMS surcharge paid to Dimagi.
    • In all cases, large messages can be charged as multiple SMS. Typically, an SMS sent using only the Roman alphabet is charged as one SMS for each 160 characters (roughly), and an SMS sent using special characters is charged as one SMS for each 70 characters (roughly).

New In Country Gateways

If Dimagi does not have an existing gateway for your country and you'd like to start a larger-scale project, it is possible to connect a new in-country gateway.   Obtaining and connecting a new gateway can take For larger high-volume projects in countries we do not already support, Dimagi can support connecting a new gateway to CommCareHQ if your subscription allows it.  SMS gateways can be purchased directly from a cell phone company in a country, or from an aggregator that resells phone numbers. Setting up a new gateway requires a significant amount of time and there are additional costs to connecting it to CommCareHQ.  If this is required for your project, please contact us.can have high costs. After identifying potential providers, please use the Aggregator Evaluation Worksheet to ensure that key questions are asked and answered during meetings with respective telcos/aggregators. Once you have selected an appropriate gateway provider based on project requirements (cost, setup time, reverse billing), the gateway can be connected to CommCareHQ with assistance from Dimagi's developer team. Please contact for more information.