RapidPro Messaging Gateway

As of v3.11.0, messages can be sent and received using RapidPro as a messaging gateway.

RapidPro configuration

Store globals

Generate a long unique key to use as the cht_api_key.

Log in to your RapidPro dashboard, go to the globals page (/global/) and create two globals with the following data:

• name: cht_url, value: https://<your-cht-instance-host>/api/v2/sms/rapidpro/incoming-messages. For security the instance host must not include basic authentication. (NB: This endpoint was added in CHT 4.1.0. If integrating with an earlier version you will need to use the earlier version with a typo in the URL: https://<your-cht-instance-host>/api/v1/sms/radpidpro/incoming-messages)
• name: cht_api_key, value: <cht_api_key>

The names of these two global variables are arbitrary, but in this document we will keep referring to the names defined above.

Then visit the RapidPro workspace settings page (/org/home/) and check your RapidPro API token (we’ll refer to this as the rapidpro_api_key).

Create a new flow

In your RapidPro dashboard, visit the flows page (/flow/) and create a new flow. It only needs to contain a webhook, to relay the message to your CHT Core instance and handle possible errors.

Configure the new webhook:

• to POST to the cht_url you configured earlier:

• set the authorization and content-type headers

• set the body to relay the message to CHT in the expected format:

@(json(object(
  "id", run.uuid,
  "from", replace(urns.tel,"tel:+", "+"),
  "content", input.text
)))

Create a new trigger

Create a trigger (/trigger/) to start the new flow when a message is not handled elsewhere.

For more details about RapidPro configuration, consult the RapidPro integration documentation.

CHT Core configuration

API keys

The RapidPro integration uses the CHT Credentials service to retrieve the API keys using the IDs rapidpro:incoming and rapidpro:outgoing. Use the CHT credentials API to securely store the credentials.
rapidpro:incoming should contain the value of the long unique key generated earlier <cht_api_key> to verify incoming requests from RapidPro.
rapidpro:outgoing should contain your RapidPro API token <rapidpro_api_key> to authenticate requests made against RapidPro’s API.

App settings

Update your app settings as follows.

{
  "sms": {
    "outgoing_service": "rapidpro",
    "rapidpro": {
      "url": "<RapidPro instance url>"
    }
  }
}