| Excerpt |
|---|
A very popular option that works in any location is to set up an Android Gateway using systems like Telerivet and a local SIM and Android device. This is our recommended approach to setting up a gateway for CommCare. |
Overview
You can setup your own Android SMS gateway with Telerivet, and integrate it with CommCare. An Android SMS gateway will use an Android phone and its SIM card to send and receive messages for CommCareHQ.
...
| Table of Contents | ||
|---|---|---|
|
Set-up Steps
Create a Telerivet Account and Connect it to Your CommCareHQ Project
...
Before proceeding, you will need an Android phone with an active SIM card. All SMS will be sent and received from this phone and SIM. Your phone will be charged according to your plan for sending and receiving SMS.
...
Below is some guidance for managing yoru Telerivet gateway. Please also visit the Telerivet User Guide, the Telerivet Gateway App instructions, and the FAQs.
What You’ll Need
You should only consider setting up a Telerivet Android gateway if :you have all of the necessary materials.
You have an Android phone that you will be using exclusively for this purpose.
The phone will always be on and charged, chared, and connected to WiFI
The phone will always be connected to wifi (or optionally, mobile data, though that may be more expensive)has an active sim card to default to if the Wifi cuts out
You will monitor the phone's balance and ensure it always has enough credit to send and receive SMS
...
. Your phone will be charged according to your plan for sending and receiving SMS.
See the Telerivet FAQ which has important information, including which phones are recommended to be used: https:
...
//telerivet.com/help/android/faq
Set Up A Telerivet Account
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.
Backup Connectivity: 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.
Set Up A CommCare Account
Once you have a phone and set up that meets this criteria, log into CommCare
Navigate 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
Managing Your Telerivet Gateway
Managing Stored Message Volume
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).
...
When sending outbound SMS, you may need to throttle the rate at which you send SMS in order to comply with regulations in the country you are sending. A good rule of thumb is to not exceed the rate of 1 SMS per second, though you should check with the regulations in the country you wish to send SMS. In order to enforce the rate limit, in the Telerivet Android app, go to Phone Settings -> Message Sending Parameters -> Delay after message sent (ms), and enter the number of milliseconds to wait between sending each SMS. For example, enter 1000 to send SMS no faster than the rate of 1 SMS per second.
...
No matter what plan you sign up for with Telerivet, there is an initial limit of 100 outgoing SMS messages an hour. This is important to be aware of, especially for larger project or big training days when a lot of SMS messages will be sent in a short period. In order to change this, open the Telerivet app on your Android phone, click SMS rate limit, and install an SMS expansion pack(s). Can download multiple.
If you have a large project, it is likely that your Telerivet gateway phone will eventually hit a memory capacity from storing all incoming and outgoing messages. To avoid this, you'll want to change the settings on Telerivet's website. Log into Telerivet, click "Phones" on the left side panel, select the phone that you are using, click "Edit Settings" on the top right, and click the following question from "Yes" to "No."
...
Managing Messaging Speed & Rates
You can read more here about Telerivet's limits here. As a note:
Inbound SMS messages do not have rate limits
Outbound SMS message do have rate limits, based on the gateways capacity. Shortcodes do not have the same rate limits.
Increasing your rate limit: The rate limit does not depend on your paid Telerivet susbcription, but it can be expanded by downloading Expansion packs from the Google Play store. You can see more instructions here.
Issues with sending: 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.
Notifications
You can setup email notifications when a phone gets disconnected or has errors by adjusting the settings for the phone on telerivet.com.
...
Read more here.
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 telerivet.com → 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.
...
Here is a guide you can download to learn about how to maintain your Telerivet Android gateway through a CommCare Messaging project.
Registration of Contacts
You still register your contacts in CommCareHQ the same way as you would if used any other SMS gateway. Information on registering mobile worker contacts is here, and information on registering case contacts is here.
(Optional) - Share Your Telerivet Gateway with Another Project
If you have already set up your Telerivet gateway on CommCareHQ, you may want to share it with another project. To do this:
Log into your original project space in CommCareHQ, and navigate to Messaging -> SMS Connectivity.
Select your pre-existing Telerivet Gatway and click
.Under "General Settings," check the box that says "Give other domains access." In the next question, type out the name of the project.
In the new project, make sure that you click "Set As Default" for the shared Telerivet gateway (example below called cc-messaging-test)
Frequently Asked Questions
How do I manage the SMS sending rate limit? Does it depend on my Telerivet subscription?
The SMS rate limit does not depend on the paid Telerivet subscription.
The SMS rate limit can be increased by downloading Expansion Packs from the Google Play store. Each additional expansion pack raises the rate limit by 60 messages per hour. You can download up to 10 expansion packs.
One way to further increase the SMS rate limit, is to purchase an additional Android phone, and add a local SIM card.
CommCare Messaging supports splitting contacts between gateways.
Is there a difference in Message Loads between inbound and outbound SMS?
Inbound SMS messages do not have rate limits
Outbound SMS message do have rate limits, based on the gateways capacity. Shortcodes do not have the same rate limits.
How do you test a gateway in multiple countries?
To test an SMS gateway in multiple countries, procure a SIM card for each country mobile operator. Start by sending test messages to each phone. Once received, send in a response to confirm that messages can be sent both ways.
For more information regarding managing your SMS system check out the Telerivet FAQ for helpful tips.
What is the volume cut-off for a Telerivet gateway versus going to Telecoms?
...
If the messaging system is meant to deliver messages en masse at a specific time of day.
...
Telerivet Gateways have an SMS rate limit, of about 600 messages per hour.
...
Often projects will calculate the daily SMS rate limit, but should actually consider the peak number of messages per hour. The daily limit per Android gateway is 14400 messages a day.
...