Building > Features > Integrations > RapidPro
Integrate interactive messaging conversations into your workflows
RapidPro is the open-source platform that powers TextIt, developed by UNICEF and Nyaruka. RapidPro allows you to visually build messaging workflows for mobile-based services. Review RapidPro’s documentation to familiarize yourself with various components that include the API. Before you embark on designing an integrated RapidPro/CHT workflow, you should start by understanding the needs of your users, identifying a problem to solve, and establishing goals. While an integrated RapidPro/CHT workflow can open up many powerful and personalized messaging capabilities, introducing an additional technology solution does come with complexities and cost. A good way to mitigate some of the complexities of setting up and hosting RapidPro yourself is to utilize a SaaS solution such as TextIt. TextIt offers transparent per message pricing and free credits to start off.
Coming up with a design to accommodate user needs requires a detailed understanding of the capabilities of both systems and conceptually where it makes sense to introduce interactions between them. Below we introduce some of the key concepts in RapidPro, but to learn more you can take one of their online courses, watch some of their videos, and check out their deployment toolkit.
Before designing your integrated RapidPro/CHT workflow, it’s important to understand a couple key functional concepts in RapidPro: Flows, Campaigns, and Triggers.
Flows are a series of steps you link together visually to define the interactions users will have. At any point in the flow, you can trigger actions such as sending an SMS, email, or calling external APIs. Flows are the base for RapidPro’s other features.
Use Case Example: Send an SMS to a patient asking if they are experiencing any new symptoms today. If so, let the patient know that a CHW will contact them. If not, let the patient know that they will receive another check-in message in three days and to contact their CHW if any new symptoms develop before then.
Additional Resources: Mastering Flows and How to Build a RapidPro Flow.
Campaigns allow you to schedule messages and flows around a date unique to each contact in a group, like a delivery date or registration date. You can add any number of Events to the Campaign.
Use Case Example: Send a daily check-in message to quarantined patients for 14 days to see if they have developed any symptoms.
Additional Resources: Creating a Campaign
Triggers allow you to control how or when a Flow begins. A Trigger can be a keyword received in a text, a point in time, a missed call, or even a follow to a Twitter handle.
Use Case Example: Start a health assessment Flow whenever a person sends the text assessment
to a specific short code.
Additional Resources: Creating a Keyword Trigger that starts a Flow
Designing an integrated workflow between multiple systems is more of an art than a science. Drafting a sequence diagram (below) is a good first step. When drafting your sequence diagram, it is useful to consider a few key integration touchpoints that are common across many integrated workflows.
A sequence diagram will help you identify the various actors in a given workflow and what the flow of data will look like. Below is an overview and example diagram for a patient initiated triage and feedback workflow.
The information below focuses on specific interactions between RapidPro and the CHT, it does not cover RapidPro specific configuration, consult RapidPro documentation and resources for that. Also, the examples and code snippets below are using TextIt, the hosted RapidPro service mentioned above.
For RapidPro to communicate with the CHT, you need to create a User in the CHT that will be used by RapidPro when calling the CHT’s APIs. This can be done from the App Management page in the CHT. When adding the user in the CHT, be sure to select the Gateway - Limited access user for Medic Gateway
Role.
Globals are shared values that can be referenced in flows, as well as broadcasts and campaigns, within your account referenced by @globals.value_name
. They allow you to create a value once and use it repeatedly without having to reenter the value. Likewise, globals make updating a shared value much easier. Rather than manually changing a value everywhere it’s used in your account, simply update the value found in your Globals
page.
Once you have configured a Global value, you can easily use it in your flows like this:
One of the most common activities you’ll want to do is trigger a Flow in RapidPro based on something that occurred in the CHT. For example… whenever a specific form is submitted in the CHT with some conditional value, start a flow in RapidPro. To do this, you will use the Outbound feature in the CHT, invoking the Flow Starts Endpoint in RapidPro.
Below is an example outbound
config in the CHT called textit-self-quarantine
that will trigger a flow in RapidPro whenever a covid_trace_follow_up
form is submitted in the CHT where symptom = no
. It will also pass an extra date value for self_quarantine_enrollment
.
{
"textit-self-quarantine": {
"relevant_to": "doc.type === 'data_record' && doc.form === 'covid_trace_follow_up' && doc.fields.trace.symptom === 'no'",
"destination": {
"base_url": "https://textit.in",
"auth": {
"type": "header",
"name": "Authorization",
"value_key": "textit.in"
},
"path": "/api/v2/flow_starts.json"
},
"mapping": {
"flow": {
"expr": "<UUID of Flow in RapidPro>'"
},
"urns": {
"expr": "[ 'tel:' + doc.fields.inputs.contact.phone ]",
"optional": false
},
"extra.self_quarantine_enrollment": {
"expr": "new Date(doc.reported_date).getDate()+'-'+ (new Date(doc.reported_date).getMonth()+1) +'-' + new Date(doc.reported_date).getFullYear()+ ' ' + new Date(doc.reported_date).getHours() + ':' + new Date(doc.reported_date).getMinutes()",
"optional": false
},
"extra.name": "doc.fields.inputs.contact.surname"
}
}
}
Once a user has completed a Flow in RapidPro, it is likely you will want to record some of the information collected in the RapidPro flow back in the CHT. This can be achieved by utilizing the Call Webhook action in RapidPro.
Step | Application | Config step |
---|---|---|
1 | CHT | Configure a JSON Form that includes the fields from RapidPro you want to send to the CHT. |
2 | RapidPro | Add a Call a Webhook node. |
3 | RapidPro | POST to the records endpoint in the CHT. If you used the Global value mentioned above, the POST will look something like @globals.api/v2/records . |
4 | RapidPro | Set a Result Name |
5 | RapidPro | Configure HTTP Headers to be Content-Type -> application/json |
6 | RapidPro | Configure the POST Body (see example below) |
Another common action you will likely need to perform in RapidPro is getting information from the CHT about a user or patient based on their phone number. You can use the contacts-by-phone API to get fully hydrated contacts associated to that phone number.
A workspace contains models for a set of RapidPro users, and it also identifies a company or project. Set up staging
and production
workspaces so that builds, tests and updates can proceed safely before and after deployment.
RapidPro supports both Android channels and SMS aggregators.
Ensure that you install the maximum number of SMS packs (available in the RapidPro SMS Channel Android app) and follow these best practices when using Android channels:
Prevent the Android channel from going to sleep. Some steps to achieve this are available on dontkillmyapp:
Background Limit
to Standard Limit and confirm that the RapidPro app has the toggle enabled in “Background Check” and all of the apps have “App Standby state: ACTIVE” in Standby apps.Automatically wake up the phone.
Alerts for when things go wrong.
Alert Email
Android channels can be used with a bulk sender to get past the 330 outgoing messages per hour.
Medic recommends that you use shared or dedicated shortcodes for SMS messaging. Dedicated shortcodes are preferred because recipients do not have to include the keyword with each response submitted. Shortcode procurement can be a lengthy process, so make arrangements for the shortcode in advance. It is possible but inconvenient to migrate to a shortcode after deployment.
Medic recommends that SMS costs be zero-rated so that respondents do not incur charges. This motivates them to respond.
Tips and best practices are listed below:
You submitted an invalid response. Reply 1 for “Yes”, 2 for “No”
. These can be customized.globals
, shared values that can be referenced inflows, as well as broadcasts and campaigns, within your account referenced by @globals.value_name
. This prevents re-entry of values in various components and allows flows to be shared easily in staging and production environments.Testing includes manual and scripted.
Manual testing
Scripted testing
These tests cover the parts that are inaccessible via manual tests. They include units that test individual components and end-to-end tests that test a flow from start to end. As a best practice, the following test pattern using the cht-conf-test-harness is recommended:
Integrate interactive messaging conversations into your workflows
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.