Versions Compared


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


SMS gateways are used by CommCareHQ to send and receive text messages.  Each SMS gateway is represented by a phone number - normally a gateway is setup for each country, but some gateway providers will let you send messages to many countries. 


If you have a phone that meets those criteria, you can get started by navigating to Messaging -> SMS Connectivity in your project space. At the bottom of this page, click "Add Another Gateway". CommCareHQ will then walk you through the steps to setup a Telerivet SMS gateway and connect it to your CommCareHQ project for sending and receiving SMS:


Step 2: Read these Important Tips for using Telerivet with CommCare Messaging

  • When creating your Telerivet account, check to see where your project falls under Telerivet's pricing. It is important to set up the right pricing structure before your project goes live. For example, it's important to ensure that the number of contacts you will be sending to falls within the limit allowed on the account.  If you want to set your Telerivet pricing to a non-free plan, make sure that when you use your credit card to add funds to "Select a plan" that you want to use. 
  • It's important to be aware of the maximum number of stored messages that your Telerivet plan allows. For example, the Test Telerivet plan only allows 500 messages to be stored in the account, so after sending and receiving 500 messages total, the account will stop sending new messages until old messages are deleted.  To have your Telerivet account automatically delete old messages, you can update the "Message Retention" setting for your Telerivet project (Dashboard -> Edit Settings).


  • You can setup email notifications when a phone gets disconnected or has errors by adjusting the settings for the phone on  To do so, click Edit Settings on the Dashboard when logged into and adjust the Email Notifications.  You can also click on the page for the phone on and click Edit Settings there for some additional Email Notifications.

  • You can request a message delivery report from Telerivet, meaning Telerivet will notify CommCare once a message has been delivered to its intended recipient(s). CommCare will then update the respective message logs accordingly with a "Delivered" status. This is useful when you need to know which or whether recipients have received the message. To enable this, sign in on → click Routes → Select the appropriate route → click Edit Settings → make sure the checkbox under "Delivery Reports" is checked.
  • Ideally, all data sent from Telerivet to Commcare will be sent through a wi-fi connection. However, if the wi-fi connection is not working or intermittently cuts out, then it's important to have a back up 3G connection. By default, Android phones won't automatically switch from Wi-Fi to mobile data if the phone is connected to the Wi-Fi network but the Wi-Fi network isn't connected to the internet. The Telerivet Android app lets you override that. From the Phone Settings screen in the Telerivet Android app, scroll to the bottom and enable "Network failover". Then Telerivet will automatically switch the phone from Wi-Fi to mobile data if it can't connect to telerivet's servers via Wi-Fi.  This may use more airtime but will result in a more reliable connection.

  • If there are problems with CommCareHQ and messages can't be sent from the gateway to CommCareHQ immediately, Telerivet will retry failed webhooks periodically for up to a day.