Gateway Options for SMS Projects
Overview
SMS gateways are used by CommCare HQ to send and receive text messages. Each gateway is represented by a phone number - this could be a long code (e.g. +1-555-123-4567) or a short code (e.g. 13341). Different types of gateways exist - use this page to determine which SMS gateway is most appropriate for your project.
For general questions about how CommCareHQ uses SMS, please visit this section on SMS basics.
Gateway Options
There are a few types of SMS gateways available for use in CommCareHQ:
Dimagi Connected Gateways: These are existing gateways that are already available in CommCareHQ (listed below). They are suitable for high-volume projects (and some support reverse-billing), but are only available in certain countries. There are a few global gateways (US phone numbers) but these are more expensive for sending and receiving international messages. Review the table below to determine which gateways support the countries for your project.
Android Gateway: This uses an Android phone to send and receive messages for your project. It's suitable for lower-volume projects and requires ongoing upkeep (topping up the phone's balance and making sure it remains connected to the internet). Instructions for using this gateway option are available here: https://dimagi.atlassian.net/wiki/x/zBnKfw.
New In Country Gateway: For larger high-volume projects in countries we do not already support, Dimagi can support 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 information@dimagi.com for more information.
Pricing per SMS can be found here: https://www.commcarehq.org/messaging-pricing
Existing CommCareHQ Gateways
These gateways are always available for use without setup time, and Dimagi manages the relationships with these gateway providers. To see a full list of available gateways, go to Messaging -> SMS Connectivity in your CommCareHQ project space. From there you can choose one to use for your project. See https://dimagi.atlassian.net/wiki/x/fCnKfw for more detailed instructions.
How to choose an SMS Gateway
Choosing the right SMS Gateway is probably one of the most important decisions you will make for your messaging project. Below are some questions to help you make that decision.
What's my project's expected volume of SMS?
If you're planning on sending more than 60 SMS per minute, you will likely need a short code. Short codes allow for higher volumes of SMS and trying to send more than 60 SMS per minute with a long code might end up in less reliable delivery rates.
Does Dimagi offer an in-country SMS Gateway in the country I'm looking for?
If Dimagi has an in-country SMS Gateway and it meets your criteria for whether you need a long or short code based on the SMS Volume question above, then you can probably use it for your project. If not, and if you can use a long code based on your volume requirements, it is recommended that you setup an Android Gateway in-country for best delivery rates. If you need a short code based on your volume requirements and Dimagi does not have one in the country you require, you may need to setup your own in country gateway (see "New In Country Gateway" above).
Can I use an international SMS Gateway?
Normally, it is not recommended to use an international SMS gateway for a live project because delivery rates tend to be worse. Experience has shown that using an in-country gateway leads to better delivery rates. However, if you test with an international gateway and are pleased with the results it might be an option for you as long as you understand that delivery rates might be lower and may change over time.
Are there any regulations that I have to comply with in the country I'm sending SMS?
Some countries have additional regulations around SMS messaging that you will have to comply with. For example, in India all messages are either considered to be "Promotional" or "Transactional". If they are considered to be "Promotional", there will be extra restrictions around those messages, such as only being able to send at certain times of the day, and not being able to send to users on the Indian Do Not Disturb list. If you want to be free from these restrictions you will have to apply for "Transactional" status for your messages through a gateway that you choose. These restrictions are specific to India, but other countries might have their own restrictions. For more information on setting up a gateway in India, please see this section below.
Comparing On-device vs Server-based SMS in CommCare
Broadly speaking, CommCare supports two ways of sending out SMS messages:
Sending an SMS directly via a CommCare form on a mobile device
Configuring SMS to be sent from CommCareHQ’s servers via an SMS Gateway
See more details on each of these implementation strategies below.
Pros and Cons (when to use each method)
Sending SMS directly from a CommCare form is good for messages that are:
Real-time
Triggered during an app workflow
Time-sensitive -- especially in areas with inconsistent mobile data
Have no privacy concerns associated with sharing a mobile user’s phone number
Using CommCare Messaging is best for:
Asynchronous alerts or reminders
Batch messages sent out to many users at once
Messages that need to be sent from an anonymous or system user
Automated, interactive SMS workflows
Sending an SMS directly via a CommCare form on a mobile device
See https://dimagi.atlassian.net/wiki/x/GSXKfw on how to implement this in CommCare form builder.
Level of effort (app-building): ~1 hour to configure your first message, several minutes for each subsequent message
User Experience: User taps on a button that says “Send SMS” inside a CommCare form. They are taken to the SMS interface of their device, where the list of recipients and message content has been pre-populated from hidden variables in CommCare. When the user taps “Send”, they are automatically returned to CommCare.
Requirements: Mobile SMS credit on the user’s phone
Caveats: Can be hard to verify if an SMS message was actually sent or not. Can’t send messages asynchronously. Messages originate directly from the mobile worker’s phone
Configuring SMS to be sent from CommCareHQ’s servers via an SMS Gateway
See on how to implement this functionality using the CommCare messaging feature and an SMS Gateway provider.
Level of effort (app-building): EXTENSIVE. Requires dev work to set up SMS Gateway compatibility internally, as well as partner-facing negotiations to set up the SMS Gateway externally. Interface is fairly user-friendly, but requires several hours of exposure before app-builders fully grasp all the details.
User Experience: Messages are delivered asynchronously. The messages typically originate from a “short code” assigned by the Telcom involved, and may be configured to accept user responses. The messages can be triggered by:
A specific date
Change in a user case property
A manual broadcast
Requirements: Activation of SMS Messaging Feature Flags (“Outgoing Messaging” and “Incoming Messaging”), Custom Dev Work to configure SMS Gateway internally, selection of SMS Gateway provider that operates within the country you’re working in, Implementation work to configure SMS Gateway externally
Caveats: Time-consuming and expensive to set up. Dimagi adds a surcharge of $0.01 per message sent. Users must sync data with the server in order to trigger SMS messages.
India Country-Specific Phone Set-up for activating CommCare HQ Messaging
Summary:
Government regulations in India to reduce spam have made it very difficult to send SMS in India and the gateways are playing catch-up to meet the regulations.
Anyone can opt into a government maintained do not disturb (DND) list.
If they are on this list we can't send them SMS unless they explicitly opt-in to receive messages from CommCare. Generally you should make sure FLWs we work with / SIMs you procure are opted in. You may also want to sign them up for DND to avoid spam, but this should be done only if you opt in.
-On the contrary, if the FLW is on the DND list for IVR, we are not able to send them phone calls using IVR unless they de-register or never sign up for DND.
In addition to working around the DND list, we have more flexibility if users specifically opt-in to receive SMS from us (details below). If users opt-in we can use a named sender ID (COMCAR), and send between the hours of 9pm and 9am. Thus, really we should have everyone opt in even if they're not on DND.
These regulations seem to keep changing and the gateways keep adjusting to fall in line. Dimagi will stay on top of this and respond to changes in regulations and communicate to partners accordingly.
The way to unsubscribe from the DND list may vary from one telco to another, making the whole process that much more complex.
Activate DND & Subscribe to CommCareHQ Messages
What you need to know/do for SMS in India:
(required) Make sure all the FLWs opt in to receive messages from CommCareHQ as part of the initial CommCare training.
(optional) Sign the FLW up for DND (to avoid spam).
Make sure all the users opt in as part of the initial CommCare training.
Notes:
Step 1 should always be done no matter what, but it absolutely has to be done if the user is on DND.
These steps also apply to all existing deployments.
To Opt In (required):
Have the user send a "START" message to +917760962755. This is a text message with the single word "start" in it.
(To unsubscribe from the messages, subscriber can send STOP message to +917760962755, although I don't think we'll encourage anyone to do this)
The success and failure auto responses for the Opt-In VN are as following:
START:
You have successfully opted to receive all messages from Dimagi Inc. To opt out of these messages in the future, please send STOP to +917760962755
You have already opted to receive all messages from Dimagi Inc. To opt out of these messages in the future, please send STOP to +917760962755
STOP:
You have successfully opted out of receiving message from Dimagi Inc. To opt in to these messages in the future, please send START to +917760962755
You have already opted out of receiving message from Dimagi Inc. To opt in to these messages in the future, please send START to +917760962755
Do Not Disturb (optional):
To activate Do Not Disturb Service: SMS 'START 0' (without quotations, zero) to 1909.
To De-Register from the DND to receive IVR messages: Have the FLW call the DND registry (NCPR) using their IVR by dialing 1909 asking to deactivate DND, or alternatively by sending an SMS 'STOP 0' to 1909.
FAQ:
What else might change in the future?
It is possible that we may eventually be restricted to only sending preapproved, templated, messages.
Opt-In notifications will be sent every month after registration to the user.
Anyone who has opted in for SMS will be receiving a monthly notice from our gateway, per new regulations. If we think this will be confusing for the FLWs you may want to start bringing it up during training.
Message from the gateway provider:
The amendment released on TRAI Regulation states that a reminder SMS has to be sent every thirty days to all Opt-in Numbers registered.
Please find the TRAI link for your reference [Page 2, Point 6.(d)]
As a part of this requirement we will be required to send monthly reminders to the Opted-In users through the Opt-In account(s).