🐍  Celebrate CircuitPython Day with us on August 19th! Sign up for our webinar: "Reimagining IoT Deployments with CircuitPython"

Search
Documentation Results
End of results
Community Results
End of results
Support
Blues.io
Notehub.io
Shop
Sign In
Search
Documentation Results
End of results
Community Results
End of results
Support
Blues.io
Notehub.io
Shop
×
HomeGuides & Tutorials
Welcome
Collecting Sensor Data
Routing Data to Cloud
Twilio SMS GuidePrerequisitesConfiguring the RouteNotecard RequestRoute VerificationAdditional Resources
Fleet Admin Guide
Using the Notehub API
Notecard Guides
Guide Listing
Asset Tracking
Attention Pin Guide
Connecting to a Wi-Fi Access Point
Debugging with the FTDI Debug Cable
Encrypting Data With the Notecard
Minimizing Latency
Serial-Over-I2C Protocol
Understanding Environment Variables
Understanding Notecard Penalty Boxes
Updating ESP32 Host Firmware
Using External SIM Cards
Using JSONata to Transform JSON
Rate this page  
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★

Twilio SMS Guide

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.

note

The complete Twilio route configuration is displayed at the bottom of the page if you want to skip ahead to the end.

  1. Navigate to the Notehub.io Route creation screen and click the Add Route button.

    Notehub.io: Route creation

  2. Select the General HTTP/HTTPS Request/Response route type.

  3. Give the route a name, and then set the URL to your Twilio Messages endpoint. For example, https://api.twilio.com/2010-04-01/Accounts/[twilio_account_sid]/Messages.json

    Be sure to replace [twilio_account_sid] with your Twilio "ACCOUNT SID".

  4. 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.

  5. 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.

  6. 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.

    This value will end up looking something like: Basic QUMwNW...lYWE2Y2Jkw==.

    Twilio.com: Account credentials

  7. 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.

  8. Specify which Notes should be sent via SMS, by updating the Select Notefiles field to twilio.qo.

  9. From the Transform JSON dropdown, select JSONata Expression.

  10. In the JSONata Expression field, enter the expression "&Body=" & body.body & "&From=" & body.from & "&To=" & body.to & "&".

    note

    You are not limited to the body of the Note when crafting a message to send to Twilio. You may utilize hardcoded strings for testing, or any key from the associated Event JSON.

    In this example, it could be particularly useful if you wanted to know which Notecard had generated the SMS message.

  11. Lastly, ensure the route is enabled, and click Create Route.

Complete Configuration

Notehub.io: Twilio Route 1 Notehub.io: Twilio Route 2

Notecard Request

The Notecard request required to provide the parameters consumed by the JSONata Expression provided above is fairly straight-forward.

  1. Expand the web console, and connect to your Notecard.

    Notehub.io: Web Console Button

  2. Update the configuration to minimize latency (for the sake of the demonstration).

    {
        "req": "hub.set",
        "product": "com.example.user:twilio",
        "mode": "continuous",
        "sync": true
    }
    note

    Be sure to substitute your product's actual ProductUID for the example string provided above.

  3. Queue the following Note onto the twilio.qo output queue.

    {
        "req": "note.add",
        "file": "twilio.qo",
        "sync": true,
        "body": {
            "body": "Hello from Notecard!",
            "from": "+1251577xxxx",
            "to": "+1314359xxxx"
        }
    }

    The from number must match your Twilio account number.

    Twilio.com: Your Twilio number

    The to number must be a number from your list of Verified Caller IDs.

    Twilio.com: Your Verified Caller IDs

    note

    The numbers provided MUST be formatted in the manner specified by the E.164 international telephone numbering plan .

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.

Webhook.site: Homepage

Update the Route URL of your Notehub Route to direct your events to Webhook.site.

Webhook.site: Requests

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.

Twilio.com: Programmable Messaging Dashboard

Check Your Phone!

SMS Note

If you have configured everything correctly, Route verification should only be as far away as your pocket!

Additional Resources

  • Mozilla: Sending Form Data
  • Twilio: Sending Messages
  • Base64Encoding.org
  • JSONata: String functions
  • Webhook.site
  • GitHub: Blues Notecard Twilio Sketch
Can we improve this page? Send us feedbackRate this page
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
© 2022 Blues Inc.Terms & ConditionsPrivacy
blues.ioTwitterLinkedInGitHubHackster.io
Disconnected
Notecard Disconnected
Having trouble connecting?

Try changing your Micro USB cable as some cables do not support transferring data. If that does not solve your problem, contact us at support@blues.com and we will get you set up with another tool to communicate with the Notecard.

Advanced Usage

The help command gives more info.

Connect a Notecard

Have a Notecard? Use USB to connect it and start issuing requests from the browser.

Sign into your free Notehub account and experiment using a simulator running the latest Notecard firmware.

Don't have an account? Sign up