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)
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 |
Preparation
This section deals with the basic configuration of RapidPro (using TextId provider) and channel (Twilio for the sake of this PoC).
- Create an account at https://www.twilio.com/try-twilio.
- Login to Twilio.
- Go to Products.
- Check Programmable SMS.
- Click the "Continue" button.
- Enter project name.
- Click the "Continue" button.
- Click the "Skip This Step" button.
- Click the "Get Started" button.
- Click the "Get a number" button.
- Click the "Choose this Number" button.
- If you country requires it, you will have to fill up the following form. After you're done click the "Save and continue" button.
- Click the "Done" button.
- Create an account at https://textit.in/.
- Login to TextI and navigate to https://textit.in/org/twilio_connect/.
- 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).
- Click "Save" button.
- 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.
- Login to TextIt and navigate to https://textit.in/org/home/.
- Read your access token.
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.
- Login to TextIt and navigate to https://textit.in/org/home/.
- Read your access token.
- Navigate to https://textit.in/flow/.
- Click the "Create Flow" button.
- Provide name for the flow.
- Click the "Create" button.
- Click the "Create Message" button.
- Select "Send a response message" option.
- Fill text box with "@extra.message".
- Click the "Ok" button.
- Read the flow's ID from the URL - https://textit.in/flow/editor/<FLOW_ID>/
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 a SMS with "Flowing Hello World via REST API!" message to the given phone number.