Gateway Options for SMS Projects

Owned by Gillian Javetski
Last updated: Jun 29, 2024 by Gillian Javetski
3 min read

About SMS Gateways

SMS gateways are used by CommCareHQ to send and receive text messages.  Each SMS 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). normally a gateway is setup for each country, but some gateway providers will let you send messages to many countries. 

SMS Gateway Options with CommCare

There are different ways that you can se up your Gateway with CommCare.

Gateway Considerations

Potential Costs

Gateways will typically require an additional cost to an organization outside of their CommCare subscription. Depending on your setup and gateway, these costs may include the following:

  • Purchase of the smartphone

  • Maintenance of a phone number or active SIM card

  • Assuring the gateway has sufficient credit

  • And may include subscription costs of the Gateway provider

In addition, CommCare also charges an additional $.01 (US) per message on all incoming and outgoing messages. More information can be found here: or here: https://www.commcarehq.org/messaging-pricing .

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.

Important Considerations

When setting up your gateway, it’s important to keep in mind the following areas:

  • Gateways act as a pass through. Delivery of SMS messages depends on the reliability of the local mobile operator. Gateways cannot send messages if they are offline or guarantee that SMSes are delivered on time.

  • In-Country Regulations: Some countries have regulations related to the volume of SMS that you send. It’s helpful to look these up as you set up your gateway.

  • Volume: If you're planning on sending more than 60 SMS per minute, you will likely need a short code via a . 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.

Ways to Send Messages

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

The table below walks through these options in greater detail.

 

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

 

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

Instructions

See on how to implement this in CommCare form builder.

See on how to implement this functionality using the CommCare messaging feature and an SMS Gateway provider.

Best 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

  • 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

Application Building LoE

~1 hour to configure your first message, several minutes for each subsequent message

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

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.

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

Mobile SMS credit on the user’s phone

Requires activation of an SMS gateway in the country you are working in

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

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.