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.
Both endpoint allow up to 100 URNS to be sent with a single request.
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.
Case | Result (s) |
---|---|
/api/v2/broadcasts.json | |
1 URN | 0,72012 |
100 URNS | 1,10757 |
/api/v2/flow_starts.json | |
1 URN | 0.75157 |
100 URNS | 1.35179 |
This section deals with the basic configuration of RapidPro (using TextId provider) and channel (Twilio for the sake of this PoC).
These steps should result in TextIt and Twilio being configured and ready to send messages.
This section will show how to send a SMS using the /broadcast endpoint.
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.
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.
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.
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.