Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 50 Next »

Overview

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.  Details on our SMS gateways can be found here (Gateway Options to Set up an SMS Project).  

If you don't want to use one of CommCareHQ's shared Gateways, or if you can't because connectivity isn't working with the countries or networks of your recipients, you can setup your own Android SMS gateway with Telerivet, and integrate it with CommCareHQ.   An Android SMS gateway will use an Android phone and its SIM card to send and receive messages for CommCareHQ.

Below are instructions on how to get setup.

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, so you will need to keep the SIM card's account balance topped up in order to help prevent interruptions of service. Click here to see the Telerivet FAQ which has important information, including which phones are recommended to be used.

Step 0 - Registration of mobile workers

Anyone who will be sending SMS into the system will need to be registered in CommConnect. Their numbers have to belong to a contact in your domain, otherwise, their messages can't be tied down to your domain and they won't show up in the message log. For mobile workers, this means going through the phone registration workflow, and for cases you just have to set the right case properties and it does it automatically. 

Step 1 - Create an account with Telerivet

  1. Create an account (or log into your existing account) at: https://telerivet.com/
  2. Setup your Android phone:
    a) 

    b)

    c) Follow the steps outlined on the screen to download and install the application. Note that you do not have to use your google account do this; can use the option to just go through Telerivet. 
    d) On the Android phone, setup Telerivet to process incoming calls.  

  3. Generate an API Key if one is not yet generated:
    a) 

    b)

    c)  After generating your API key, please write down the API Key, the Project ID and Phone ID, or keep the Telerivet tab open online so that you can refer to this information in a few minutes. 

  4. Configure Telerivet to notify CommCareHQ when SMS are sent to your phone:
    a) 

    b)

    c) Please type in the information as shown below. For the webhook URL, be sure to include https and a "/" at the end of the URL. This is very important. Make sure to also write down the "Webhook secret" somewhere as well (you will need it later). 

Step 2 - Integrate your Telerivet account with CommCareHQ

  1. Log in to your project space in CommCareHQ, and navigate to Messaging -> SMS Connectivity.  Under "Create Another Connection", choose "Telerivet (Android)" and click "Create Another Gateawy".
  2. Enter the following required fields (the rest are optional):

    FieldValue to Enter
    NameEnter a short but descriptive name for you to identify this connection.
    Reply to Phone NumberAdd the phone number of the gateway that you are using.
    API KeyEnter the value from your Telerivet account obtained from step 1.3 above.
    Project IDEnter the value from your Telerivet account obtained from step 1.3 above.
    Phone IDEnter the value from your Telerivet account obtained from step 1.3 above.
    Webhook Secret

    Enter the value from your Telerivet account obtained from step 1.4 above.

  3. Then save. 


  4. For most projects, you will want to click "Set As Default" next to the Telerivet gateway.  This will use the Telerivet gateway as the default gateway for any future SMS from this project.

Step 3 (Optional) - Copy Your Telerivet Gateway to a New Domain

If you have already set up your Telerivet gateway on CommCareHQ, you may want to copy it over to another domain for a different project. To do this: 

  1. Log into your original project space in CommCareHQ, and navigate to Messaging -> SMS Connectivity. 
  2. Select your pre-existing Telerivet Gatway and click  .

  3. Under "General Settings," check the box that says "Give other domains access." In the next question, type out the name of the domain. 
  4. In your new domain, make sure that you click "Set As Default" for the copied Telerivet gateway. 

 

Important Tips for using Telerivet with CommConnect

  • When setting your gateway, 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. 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. 
  • 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." 
  • You can setup email notifications when a phone gets disconnected or has errors by adjusting the settings for the phone on telerivet.com.
  • 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.

 

  • No labels