This page will explain some basic concepts of SMS Messaging in CommCareHQ.
How CommCare HQ Sends Messages
CommCareHQ uses an SMS Gateway to send and receive messages. SMS gateways are phone numbers provided by other companies (or cell phone companies) that connect to the cell phone network to send and receive messages. CommCareHQ is connected to multiple gateways to support different countries.
More information on Dimagi's existing gateways can be found Gateway Options for SMS Projects.
Using an Android Gateway
If your country isn't supported by Dimagi's existing gateways you can use an Android-based phone to send and receive messages for your project. This will use the phone's SIM card and SMS balance. Dimagi has partnered with Telerivet to use their system to support Android gateways. The Android phone will connect to CommCareHQ using the internet to know when to send messages and to send incoming messages to CommCareHQ.
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
Depending on the gateway used, it can be a short code or a long code. Long codes are similar to regular phone numbers. Short codes are special phone numbers that have a specific name (ex. CommCare) or a shorter phone number and can be used to send a very high volume of messages. Short codes also allow for reverse billing.
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 you (the gateway) will pay for messages.
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 non-Android gateway, Dimagi will charge a per-message fee. This fee differs based depending on which gateway you're using. For Android gateways, you typically have to pay a fee to Telerivet for use of their application and service, and then pay for the cost of messages to and from the phone.
New In Country Gateways
For larger high-volume projects in countries we do not already support, Dimagi can support purchasing and connecting a new gateway to CommCareHQ. 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 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 we connected to CommCareHQ with assistance from Dimagi's developer team. Please contact firstname.lastname@example.org for more information.