Twilio Route
Notehub.io can support a broad range of API endpoints by utilizing the Route feature. This guide provides instructions for leveraging the General HTTP/HTTPS Request/Response Route type to invoke the Twilio API, thus enabling your Notecard applications to communicate and send alerts over SMS.
Prerequisites
In order to follow the instructions in this guide, you'll need the following:
- A Notecard assigned to a Notehub.io project, with data synching from the Notecard to Notehub.io.
- A Twilio account, with at least one Verified Caller ID established. A verified caller ID is required in order to send messages from your Twilio account. Typically, this would be your personal telephone number.
Configuring the Route
To send SMS messages, the Twilio API expects form data with three key/value
pairs (Body, From and To). Transforming a Note body into an
HTTP body for Twilio requires some special handling. This can be
achieved using a JSONata expression to massage the data into the desired form.
JSONata is traditionally used to transform input data into output JSON, but it
can also be used, with a couple of tricks, to craft a standard HTTP body.
In JSONata, the string "Hello, world!" is rendered as "Hello, world!",
quotation marks included. This causes a problem, because the content type,
application/x-www-form-urlencoded, is not expecting enclosing quotation
marks. Fortunately, you can prefix a string with an ampersand (&) and
JSONata will interpret the leading quotation mark (") as an empty form
parameter of the same name. Likewise, an ampersand at the end of the
string interprets the final quotation mark as a redefinition of the
earlier dummy parameter. Upon receipt, Twilio discards the unknown
parameter, and continues parsing the incoming request.
Navigate to the Notehub.io Route creation screen.
Select the "General HTTP/HTTPS Request/Response" option from the Route Type dropdown.
The Twilio API expects two headers with each request. Select the "Additional Headers" option from the HTTP Headers dropdown, and set the "Authorization" and "Content-Type" headers in the following steps.
For the first header, set the name as "Authorization", and set the value to "Basic" followed by your authorization token. This token can be generated by base 64 encoding your Twilio account SID and authentication token, with a colon separating the two (
<account_sid>:<auth_token>). You can obtain the Account SID and Token from your Twilio dashboard.
For the second header, set "Content-Type" as the name and "application/x-www-form-urlencoded" as the value. This will ensure that events are properly sent to the Twilio API as form data.
Next, set the Route URL to your Twilio Messages endpoint. For example,
https://api.twilio.com/2010-04-01/Accounts/[twilio_account_sid]/Messages.jsonSpecify which Notes should be sent via SMS, by updating the Select Notefiles field to "twilio.qo".
From the Transform JSON dropdown, select "JSONata Expression".
In the JSONata Expression field, enter the expression
"&Body=" & body.body & "&From=" & body.from & "&To=" & body.to & "&".To safeguard yourself, you should update the Rate Limit dropdown, with the "Limited Request Rate" and set the Requests per Second to "1". This may help to prevent you from accidentally exhausting your Twilio credit.
Lastly, ensure the Enabled checkbox is checked, and click Save.
Complete Configuration
Notecard Request
The Notecard request required to provide the parameters consumed by the JSONata Expression provided above is fairly straight-forward.
Expand the web console, and connect to your Notecard.
Update the configuration to minimize latency (for the sake of the demonstration).
{ "req": "hub.set", "product": "com.example.user:twilio", "mode": "continuous", "sync": true }Queue the following Note onto the
twilio.qooutput queue.{ "req": "note.add", "file": "twilio.qo", "sync": true, "body": { "body": "Hello from Notecard!", "from": "+1251577xxxx", "to": "+1314359xxxx" } }The
fromnumber must match your Twilio account number.
The
tonumber must be a number from your list of Verified Caller IDs.
Route Verification
Once you've created a Twilio Route in Notehub, you can verify that it is working through the Notehub Events table, Webhook.site, Twilio.com, or by looking at your phone.
Verify on Notehub.io
Notehub.io provides a Route Log for each event. To access it, click on an individual event on the Events view, then click the "Details" link.
Then, click on the "Route Log" tab. If your Twilio Route is properly configured, the response from Twilio will be a JSON object describing the message results.
If the server returns an error, Notehub.io will display error details in the Route Log.
Verify with webhook.site
Since we are pushing Notehub to its limits, it can be difficult to diagnose any errors you encounter. To make it easier, we can route our event information to Webhook.site and see the actual output of our JSONata expression. Using Webhook.site is easy. To get started, navigate to https://webhook.site and get a session specific endpoint so you can route your events.
Update the Route URL of your Notehub Route to direct your events to Webhook.site.
Look to the Form values section, and ensure your form data looks correct.
Verify with Twilio.com
After messages have been received by the Twilio API, Twilio provides the Programmable Messaging Dashboard to view your messages and statistics.
Check Your Phone!
If you have configured everything correctly, Route verification should only be as far away as your pocket!
