RapidPro Messaging Gateway

Integration for sending and receiving messages

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/v1/sms/radpidpro/incoming-messages. For security the instance host must not include basic authentication.
  • 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:
  "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, please consult the RapidPro integration documentation.

CHT Core configuration

API keys

The API keys should be treated as securely as a password as anyone with access to them will be able to send messages using your account. Therefore, we store them in the CouchDB configuration.

To add the credentials to the admin config you need to either PUT the value using curl or similar:

curl -X PUT https://<user>:<pass>@<domain>/_node/couchdb@ -d '"<cht_api_key>"'
curl -X PUT https://<user>:<pass>@<domain>/_node/couchdb@ -d '"<rapidpro_api_key>"'

You can also add it via Fauxton:

  • Navigate to the Config screen
  • Click Add Option
  • The Section should be medic-credentials, the Name should be rapidpro:incoming or rapidpro:outgoing, and the value should be the relevant API key.
  • Click Create
  • You should then be able to see your credential in the list of configuration shown

App settings

Update your app settings as follows.

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

CHT Applications > Reference > app_settings.json > .sms

SMS Settings: Instructions and schema for defining SMS settings

CHT Applications > Quick Guides > Forms > App Form SMS

Trigger calls and SMS from within the form, or send an SMS once submitted.

CHT Applications > Quick Guides > Messaging > SMS States

Overview of the possible states of SMS messages

CHT Applications > Quick Guides > Messaging > Message Loops

How to avoid messaging loops

CHT Applications > Quick Guides > Messaging > Contact IDs

Using unique short codes to identify places and people via messaging