Introduction

RapidPro is software for communicating with many people via different messaging channels and is commonly used by aid agencies such as UNICEF.

We provide an easy to use integration for MoyaApp detailed below. If you run into any issues, or have questions or feedback, please let us know by sending a message to api-support@moya.app.

Setup steps

Get a MoyaApp token and endpoint

Please contact us at api-support@moya.app with your details to get the account set up. We will provide you with a token, and optionally a number if you don't have an existing number to use.

RapidPro configuration

In your RapidPro/TextIt deployment, go to the "Add a Channel" page and choose "External API".

We support rapidpro quick replies and these can be enabled by adding {{quick_replies}} to the request body as shown below

Configure the following parameters (many of which are just left at the default values):

URN Type: Phone Number
Number: Your MoyaApp Business Messaging API account phone number
Method: HTTP Post
Encoding: Default Encoding
Content type: URL Encoded
Max length: 2048
Authorization Header Value: The token we provided you with
Send URL: https://messaging-bridge.moya.app/v1/webhook/rapidpro/
Request Body: id={{id}}&text={{text}}&to={{to_no_plus}}{{quick_replies}}
MT Response check - leave blank

Once you have submitted this page, the integration will be configured in RapidPro.

You will then be presented with a page showing the configuration. Please provide us with the "Received URL" so we can forward messages from users to your RapidPro instance, and then the setup will be complete.

Send datafree images in Rapidpro

In order to send a datafree image/document in your rapidpro chatbot you first have to create a datafree url for your image/document using the instructions documented here Once you have a datafree url for your image you can send it by calling a webhook from your chat flow. Please note that this link is only valid for 30 days

{
    "to": "@(replace(input.urn, "tel:+", ""))",
    "recipient_type": "individual",
    "type": "image",
        "image": {
            "url": "datafree_image_url"
        }
}

Refer to images below on how the setup should look like in rapidpro

Post body

Request headers

Make KYC request

In your rapidpro chat flow you can make a kyc request in two steps as documented here

Before you start you may need to set a global variable in rapidpro for the KYC url. The value of the global should be https://api.moya.app/v1/user_data and the name KYC URL

Make KYC data request
Fetch data

{
    "reason": "Your reason",
    "data": [
        {
            "property": "first_name",
            "reason": "Your reason",
            "required": true
        },
        {
            "property": "last_name",
            "reason": "Your reason",
            "required": true
        }
    ]
}

1. KYC data request

Make a KYC request in rapidpro as shown in the image below. The webhook call is a POST request to @globals.kyc_url/start/@(replace(input.urn, "tel:+", "")). Name the result of the flow as start_kyc_data_request

A successful request will return a request id. Use the request id to fetch KYC data.

2. Fetch Data

In order to fetch user data after successful data request, you make another webhook call. This time it should be a GET request and the get url should look like:

@globals.kyc_url/fetch/@(run.results.start_kyc_data_request.extra.requestId)?long_poll=30

@(run.results.start_kyc_data_request.extra.requestId) will get the request id from the previous step that you named start_kyc_data_request.

This request has two possible responses, completed and pending. Completed means the user data request has been completed and you can move to the next step. Pending means the request has not yet been approved or denied. To handle these two cases you need to create a "split by custom expression" node in your rapidpro flow.

Connect the pending end of the split to the previous node if the result is pending and if the result is approved you can continue building other parts of the flow. User data can be accessed from other parts of the flow like @run.results.fetch_kyc_data.extra.results.first_name.value

@run.results.fetch_kyc_data.extra.results refers to the results for the "fetch data" step and first_name.value refers to the value of the first name returned by the KYC API

One-shot data request

Some parameters can be requested without needing user feedback and these properties are documented in this section. If you are requesting parameters that are granted automatically without needing any user feedback, make a webhook request for one-shot data retrieval via POST request to the following endpoint:

@globals.kyc_url/fetch/@(replace(input.urn, "tel:+", ""))

Ensure that the variable @globals.kyc_url is set to https://api.moya.app/v1/user_data and the authorization header is set to the correct moya token. The request payload should like the json below.

Example payload

{
    "data": [
        {"property": "device_platform"}, 
        {"property": "app_version"}
    ]
}

Example response

{
    "status": "completed",
    "results": {
        "device_platform": {
            "status": "approved",
            "source": "moya-stats",
            "value": "android",
            "timestamp": "2024-03-05T07:12:11"
        },
        "app_version": {
            "status": "approved",
            "source": "moya-stats",
            "value": "6.2.0",
            "timestamp": "2024-03-05T07:12:11"
        }
    }
}

Once the call is done, you can then use the results in other RapidPro nodes like @webhook.results.app_version.value

Post body

Request headers

Trigger a chat flow via api

Rapidpro allows you to trigger a chat flow using an api. To trigger a flow you need to have the flow uuid, and the recipient number(urn).

How to get the flow uuid

In rapidpro, go to the flow you want to trigger and copy the last part of the url as shown below.

After getting the flow uuid, you can trigger the flow by making a post request to the rapidpro api as shown in the example curl below.

Example request

curl --location 'rapidpro_base_url/api/v2/flow_starts.json' \
--header 'Authorization: Token {rapidpro_token}' \
--header 'Content-Type: application/json' \
--data '{
    "flow": "{flow_uuid}",
    "urns": ["tel:{user_number}"]
}'

The rapidpro token can be found in Rapidpro workspace settings as shown on the image below.

NB: The user number should be in the international format without the + sign eg 27772098000

If the request is successful, the chat flow should be triggered and the user should be able to chat with the bot.