Proof of Concept: RapidPro integration

This article shows as a Proof of Concept for integration with RapidPro. It presents all steps that have to be done from setting up required accounts to sending a message using both broadcasts and flows.

Restrictions

Max URN per request

Both endpoint allow up to 100 URNS to be sent with a single request.

URN format

Quote from https://textit.in/api/v2/#urn-values

URN Values

We use URNs (Uniform Resource Names) to describe the different ways of communicating with a contact. These can be phone numbers, Twitter handles etc. For example a contact might have URNs like:

• tel:+250788123123
• twitter:jack
• mailto:jack@example.com

Phone numbers should always be given in full E164 format.

Average request times (for 100 requests)

Preparation

This section deals with the basic configuration of RapidPro (using TextId provider) and channel (Twilio for the sake of this PoC).

1. Create an account at https://www.twilio.com/try-twilio.
   
2. Login to Twilio.
3. Go to Products.
   
4. Check Programmable SMS.
   
5. Click the "Continue" button.
6. Enter project name.
7. Click the "Continue" button.
8. Click the "Skip This Step" button.
9. Click the "Get Started" button.
   
10. Click the "Get a number" button.
    
11. Click the "Choose this Number" button.
    
12. If you country requires it, you will have to fill up the following form. After you're done click the "Save and continue" button.
    
13. Click the "Done" button.
    
14. Create an account at https://textit.in/.
    
15. Login to TextI and navigate to https://textit.in/org/twilio_connect/.
    
16. Fill Account SID and Auth Token. This information can be found on the https://www.twilio.com/console page under account SID and auth token (click View to display).
    
17. Click "Save" button.
18. Click the previously-configured phone number.
    

These steps should result in TextIt and Twilio being configured and ready to send messages.

Sending a message using /broadcast

This section will show how to send a SMS using the /broadcast endpoint.

1. Login to TextIt and navigate to https://textit.in/org/home/.
2. Read your access token.
   

3. Execute the following curl command

   curl -H "Authorization: Token <YOUR_ACCESS_TOKEN>" -X POST -H "Content-Type: application/json" -d '{"text": "Broadcasting Hello World via REST API!", "urns": ["tel:<YOUR_PHONE_NUMBER>"]}' https://textit.in/api/v2/broadcasts.json 
   

This should result in sending a SMS with "Broadcasting Hello World via REST API!" message to the given phone number.

Sending a message using /flow_start

This section will show how to send a SMS using the /flow_start endpoint. This require some preparation before we can actually use the REST API.

1. Login to TextIt and navigate to https://textit.in/org/home/.
2. Read your access token.
   
3. Navigate to https://textit.in/flow/.
4. Click the "Create Flow" button.
   
5. Provide name for the flow.
   
6. Click the "Create" button.
7. Click the "Create Message" button.
   
8. Select "Send a response message" option.
9. Fill text box with "@extra.message".
   
10. Click the "Ok" button.
11. Read the flow's ID from the URL - https://textit.in/flow/editor/<FLOW_ID>/

12. Execute the following curl command

    curl -H "Authorization: Token <YOUR_ACCESS_TOKEN>" -X POST -H "Content-Type: application/json" -d '{"urns": ["tel:<YOUR_PHONE_NUMBER>"], "extra": {"message": "Flowing Hello World via REST API!"}, "flow": "<FLOW_ID>"}' https://textit.in/api/v2/flow_starts.json 
    

This should result in sending an SMS with "Flowing Hello World via REST API!" message to the given phone number.

Summary

Overall, the flow_start endpoint would provide us with more features, but at a cost of being configuration heavy. The fact that the flows can't be created or modified by the REST API means that all the messages would have to reside inside the TextIt/RapidPro instance and would have to be added for all implementation by hand. The /broadcasts endpoint does not provide message customization or internalization but can be used easily after setting up the TextIt/RapidPro instance.

Both endpoints are restricted by the ability to send 100 URN with a single request so we should definitely add that into consideration when we introduce a batch endpoint for sending OpenLMIS notifications. Currently, the notification service only allows sending notifications to a single user.

Because of that, and the fact that the /flow-starts endpoint requires so much configuration I think that the /broadcasts endpoint is a better fit for 3.6 requirements.