CHT Applications > Features > Integrations > RapidPro
Integrate interactive messaging conversations into your workflows
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 mutliple 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.
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.