RapidPro Module

The RapidPro module allows for interoperability between MOTECH and RapidPro. MOTECH users can use this module to configure task actions that perform operations in RapidPro and task triggers corresponding to event notifications from RapidPro.

This module documentation assumes familiarity with MOTECH tasks and RapidPro concepts and entities. If you are unfamiliar with RapidPro, the RapidPro webpage has extensive documentation and how-to videos: https://community.rapidpro.io/

Setup

This module has a very simple set up. Navigate to the module settings page and enter the following information:

  • The RapidPro API key - Navigate to the RapidPro user account page to copy the key. Paste the key in the text box.
  • The API version number - Currently, the RapidPro API is at version number 1.

Web Hooks

Web hooks are HTTP callbacks that allow RapidPro client applications to be notified when certain events occur in RapidPro. The RapidPro module can recieve and process web hooks. When this module receives a web hook, it is converted to a MOTECH event. These events can be utilized in the Tasks module.

This module can receive web hook requests at the following URL : HTTP POST [MOTECH base URL]/module/rapidpro/web-hook To learn more about how to configure and use web hooks, consult the RapidPro documentation.

Tasks Module Integration

Data Source

RapidPro contacts are available as a datasource. The following fields can be accessed:

  • External ID - The unique string value that corresponds to a RapidPro contact. This will generally be an ID used by an external system, such as Commcare.
  • Contact UUID - The unique ID generated by RapidPro that corresponds to a RapidPro contact.
  • Name - The name of the contact.
  • Phone Number - The unique phone number for the contact.
  • Language - The language spoken by the contact.
  • Fields - A set of key value pairs that contain additional details about a contact.
  • Blocked - Boolean value.
  • Failed - Boolean value.

Task Triggers

Contact Created

This event is triggered when a contact is created via MOTECH. The following fields can be accessed:

  • External ID
  • Contact UUID
  • Name
  • Phone Number
  • Language
  • Fields
  • Blocked
  • Failed

Contact Updated

This event is triggered when a contact is updated via MOTECH. The following fields can be accessed:

  • External ID
  • Contact UUID
  • Name
  • Phone Number
  • Language
  • Fields
  • Blocked
  • Failed

Contact Deleted

This event is triggered when a contact is deleted via MOTECH. The following fields can be accessed:

  • External ID
  • Contact UUID

Contact Added to a Group

This event is triggered when a contact is added to a group via MOTECH. The following fields can be accessed:

  • External ID
  • Contact UUID
  • Name - The contact’s name
  • Language
  • URNs - A list of resources to contact a contact. For example a phone number (tel:+1234567890)
  • Contact Group UUIDs - A list of the RapidPro IDs for the groups the contact currently has membership in.
  • Blocked
  • Failed
  • Modified On - The time and date of the last time the contact was modified.
  • Group Name - The human readable name of the group the contact was added to.
  • Group UUID - The RapidPro ID of the group the contact was added to.

Contact Removed from a Group

This event is triggered when a contact is removed from a group via MOTECH. The following fields can be accessed:

  • External ID
  • Contact UUID
  • Name
  • Language
  • URNs
  • Contact Group UUIDs
  • Blocked
  • Failed
  • Modified On
  • Group Name
  • Group UUID

Flow Run Started for a Contact

This event is triggered when a flow run is started for a contact via MOTECH. The following fields can be accessed:

  • External ID
  • Contact UUID
  • Name
  • Language
  • URNs
  • Flow UUID - The unique ID for the flow.
  • Restart Participants - Boolean value indicating whether to restart the flow run for contacts currently in the middle of a flow run for the flow.
  • Flow - Integer value identifying the flow instance.
  • Flow Run Created On - The date and time the flow run was created.
  • Flow Run Expired On - The date and time the flow run expired, if it has already expired.
  • Flow Run Expires On - The date and time the flow run will expire, if it hasn’t yet expired.
  • Run - Integer value identifying the flow run instance.

Flow Run Started for a Group

This event is triggered when a flow run is started for a group of contacts via MOTECH. The following fields can be accessed:

  • Flow UUID
  • Flow Name - The name of the flow.
  • Group Name - The name of the group.
  • Group UUID - The unique ID for the group.
  • Restart Participants
  • Contact UUIDs - The unique IDs for all of the contacts in the group.

Error Starting flow for Contact (by Flow Name)

This event is triggered when an error is encountered while attempting to start a flow for a contact via MOTECH. The following fields can be accessed:

  • External ID
  • Flow Name
  • Restart Participants
  • Error Message - A human readable message describing the nature of the error.
  • Extra - The set of key value pairs containing additional data for the flow run request.

Error Starting flow for Contact (by Flow UUID)

This event is triggered when an error is encountered while attempting to start a flow for a contact via MOTECH. The following fields can be accessed:

  • External ID
  • Flow UUID
  • Restart Participants
  • Error Message
  • Extra

Error Starting flow for Group (by Flow Name)

This event is triggered when an error is encountered while attempting to start a flow for a group via MOTECH. The following fields can be accessed:

  • Group Name
  • Flow Name
  • Restart Participants
  • Error Message
  • Extra

Error Starting flow for Group (by Flow UUID)

This event is triggered when an error is encountered while attempting to start a flow for a group via MOTECH. The following fields can be accessed:

  • Group Name
  • Flow UUID
  • Restart Participants
  • Error Message
  • Extra

Web Hook: Recieved SMS

This event is triggered when the RapidPro module recieves a web hook from RapidPro indicating that an SMS was received. The following fields can be accessed:

  • Time - The date and time that this message was received.
  • Relayer - The id of the channel that received this message
  • SMS - The id of this message
  • Relayer Phone - The phone number of the channel that received this message
  • Phone Number - The E164 phone number of the sender of this message
  • Text - The text of the message.
  • Direction - The direction of the message, either I for incoming or O for outgoing

Web Hook: Sent SMS

This event is triggered when the RapidPro module recieves a web hook from RapidPro indicating that an SMS was sent. The following fields can be accessed:

  • Time
  • Relayer
  • SMS
  • Relayer Phone
  • Phone Number
  • Text
  • Direction
  • Status - The current status of this message, one of Q,S,D,E or F

Web Hook: SMS Delivered

This event is triggered when the RapidPro module recieves a web hook from RapidPro indicating that an SMS was successfully delivered. The following fields can be accessed:

  • Time
  • Relayer
  • SMS
  • Relayer Phone
  • Phone Number
  • Text
  • Direction
  • Status

Web Hook: Incoming Call

This event is triggered when the RapidPro module recieves a web hook from RapidPro indicating that an incoming call was received. The following fields can be accessed:

  • Time
  • Relayer
  • Relayer Phone
  • Phone Number
  • Call - The id of this call
  • Duration - The length in seconds that this call lasted, 0 for missed calls

Web Hook: Missed Call

This event is triggered when the RapidPro module recieves a web hook from RapidPro indicating that an incoming call was missed. The following fields can be accessed:

  • Time
  • Relayer
  • Relayer Phone
  • Phone Number
  • Call
  • Duration

Web Hook: Call Connected

This event is triggered when the RapidPro module recieves a web hook from RapidPro indicating that an outgoing call was connected. The following fields can be accessed:

  • Time
  • Relayer
  • Relayer Phone
  • Phone Number
  • Call
  • Duration

Web Hook: Call Not Connected

This event is triggered when the RapidPro module recieves a web hook from RapidPro indicating that an outgoing call was not connected. The following fields can be accessed:

  • Time
  • Relayer
  • Relayer Phone
  • Phone Number
  • Call
  • Duration

Web Hook: Alarm

This event is triggered when the RapidPro module recieves a web hook from RapidPro indicating that either the Andriod device has a low battery, unsent messages, or connectivity problems. The following fields can be accessed:

  • Relayer
  • Relayer Phone
  • Power Level - The current power level of the channel
  • Power Status - The current power status, either CHARGING or DISCHARGING
  • Power Source - The source of power, ex: BATTERY, AC, USB
  • Network Type - The type of network the device is connected to. ex: WIFI
  • Pending Message Count - The number of unsent messages for this channel
  • Retry Message Count - The number of messages that had send errors and are being retried
  • Last Seen - The time that this channel last synced in ECMA-162 format

Web Hook: Flow Point Reached

This event is triggered when the RapidPro module recieves a web hook from RapidPro indicating that a user has reached an API node in a flow. The following fields can be accessed:

  • Relayer
  • Relayer Phone
  • Phone Number
  • Flow
  • Step - The uuid of the step which triggered this event
  • Time - The time that this step was reached by the user in ECMA-162 format
  • Values - The values that have been collected for this contact thus far through the flow (JSON)

Web Hook: Error

This event is triggered when an error is encountered while processing a web hook. The following fields can be accessed:

  • Error Message
  • Event Key - The string value representing the type of web hook event.
  • Request Values - A map of all the values in the web hook request from RapidPro.

Web Hook: Custom

This event is triggered when the RapidPro module recieves a custom web hook request from RapidPro. The following fields can be accessed:

  • Values - A map of all the values in the custom web hook request.

Task Actions

Create Contact

This action is used to create a contact. The following fields can be utilized:

  • External ID (required)
  • Name (required)
  • Phone Number (required)
  • Language
  • Fields
  • Blocked
  • Failed

Update Contact

This action is used to update a contact. The following fields can be utilized:

  • External ID (required)
  • Name (required)
  • Phone Number (required)
  • Language
  • Fields
  • Blocked
  • Failed

Delete Contact

This action is used to delete a contact. The following fields can be utilized:

  • External ID (required)

Add Contact to Group

This action is used to add a contact to a group. The following fields can be utilized:

  • External ID (required)
  • Group Name (required)

Remove Contact from Group

This action is used to remove a contact from a group. The following fields can be utilized:

  • External ID (required)
  • Group Name (required)

Start Flow for Contact by Flow Name

This action is used to start a flow for a contact. The following fields can be utilized:

  • External ID (required)
  • Flow Name (required)
  • Restart Participants
  • Extra - A set of key value pairs for adding extra fields to the flow run request.

Start Flow for Contact by Flow UUID

This action is used to start a flow for a contact. The following fields can be utilized:

  • External ID (required)
  • Flow UUID (required)
  • Restart Participants
  • Extra

Start Flow for Group by Flow Name

This action is used to start a flow for a group. The following fields can be utilized:

  • Group Name (required)
  • Flow Name (required)
  • Restart Participants
  • Extra

Start Flow for Group by Flow UUID

This action is used to start a flow for a group. The following fields can be utilized:

  • Group Name (required)
  • Flow UUID (required)
  • Restart Participants
  • Extra