Key Considerations while Setting up an Android Gateway (Telerivet)
- Arti Sahu
Analytics
SMS gateways are used by CommCare HQ to send and receive text messages. A gateway is represented by a phone number. If you are unable to use or choose not to use a commercial gateway, you can setup your own Android SMS gateway with Telerivet. The purpose of this guideline is to introduce implementers to the Telerivet gateway. Telerivet is an Android based gateway which will use an android phone and its SIM card to send and receive for CommCare HQ.
The purpose of this wiki is to summarize some key considerations when setting up a Telerivet Gateway, for a step-by step guide on how to set up a Telerivet gateway follow the wiki on Setup an Android SMS Gateway.
When creating your Telerivet account, check to see where your project falls under Telerivet pricing. It is important to set up the right pricing structure before your project goes live. For example, it is important to ensure that the number of contacts you will be sending to falls within the limit allowed on the account. More details can be found under pricing.
There is a free test option which will give you 50 SMSes for free. Note that you will still be responsible for your own SMS credit and WIFI connection for the phone, but this is a good way to learn more about Telerivet.
It is 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 in 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). Below is an example of how a Telerivet reporting dashboard looks like.
When sending outbound SMS, you may need to throttle the rate at which you send SMS 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 use the CommCare Messaging feature in. 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. 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 will want to change the settings on Telerivet 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."
You can setup email notifications when a phone gets disconnected or has errors by adjusting the settings for the phone on telerivet.com. To do so, click Edit Settings on the Dashboard when logged into telerivet.com and adjust the Email Notifications. You can also click on the page for the phone on telerivet.com and click Edit Settings there for some additional Email Notifications.
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 is important to have a backup 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 cannot connect to Telerivet 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 cannot be sent from the gateway to CommCareHQ immediately, Telerivet will retry failed webhooks periodically for up to a day.
You can also send a once off SMS to test the Gateway and navigate to Message history report and retrieve the messaging event. The Gateway should say Telerivet if the connection is functioning correctly