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 page on SMS basics.
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: Setup an Android SMS Gateway
- 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 firstname.lastname@example.org 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 Setup SMS Connection for Project 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 help page.