Scaling an IoT deployment? Join our webinar on May 28th where we dive into real-world scaling pain points and how to overcome them.

Blues Developers
What’s New
Resources
Blog
Technical articles for developers
Newsletter
The monthly Blues developer newsletter
Terminal
Connect to a Notecard in your browser
Developer Certification
Get certified on wireless connectivity with Blues
Webinars
Listing of Blues technical webinars
Blues.comNotehub.io
Shop
Docs
Button IconHelp
Notehub StatusVisit our Forum
Button IconSign In
Sign In
Sign In
Docs Home
What’s New
Resources
Blog
Technical articles for developers
Newsletter
The monthly Blues developer newsletter
Terminal
Connect to a Notecard in your browser
Developer Certification
Get certified on wireless connectivity with Blues
Webinars
Listing of Blues technical webinars
Blues.comNotehub.io
Shop
Docs
Guides & Tutorials
Collecting Sensor Data
Routing Data to Cloud
Building Edge ML Applications
Best Practices for Production-Ready Projects
Twilio SMS Guide
PrerequisitesConfiguring the RouteCustomize with Placeholder Variables and JSONataTesting the RouteDebugging the Route
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
Diagnosing Cellular Connectivity Issues
Diagnosing GPS Issues
Encrypting and Decrypting Data with the Notecard
Feather MCU Low Power Management
Minimizing Latency
Notecard Communication Without a Library
Recovering a Bricked Notecard
Remote Command and Control
Sending and Receiving Large Binary Objects
Serial-Over-I2C Protocol
Understanding Environment Variables
Understanding Notecard Penalty Boxes
Updating ESP32 Host Firmware
Using External SIM Cards
Using JSONata to Transform JSON
homechevron_rightDocschevron_rightGuides & Tutorialschevron_rightTwilio SMS Guide

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 Twilio route type to invoke the Twilio API, thus enabling your Notecard applications to communicate and send alerts over SMS.

See examples of using Twilio for SMS messaging in these accelerator projects.

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. (If you're unsure how to do this check out the Notecard quickstart.)
  • A Twilio account , with at least one Verified Caller ID established. A verified caller ID is required to send messages from your Twilio account. Typically, this is your personal telephone number.

Configuring the Route

To send SMS messages, you must first create a Notehub route that will automatically forward your data from Notehub events to the Twilio SMS API.

  1. Within your Notehub project, navigate to the Routes screen and then click the New Route button.

    Notehub.io: Route creation

  2. Select the Twilio route type.

    The Twilio route type in Notehub

  3. Give the route a name, for example Twilio.

    Location of the route name in Notehub

  4. In your Twilio Console, locate your Account Info, and then copy/paste the Account SID, Auth Token and Twilio phone number to your Notehub route as shown in the image below.

    How to provide Twilio data in a Notehub route

  5. Next, provide the phone number you'd like to receive SMS messages (usually your personal phone number while testing) in the Notehub route's To Number field.

    note
    • The To Number number must be a Verified Caller ID in Twilio. Twilio requires you to validate one number when creating an account, so if you're using your personal number you likely already verified it.
    • The number provided MUST be formatted in the manner specified by the E.164 international telephone numbering plan , which it will be if you copy/paste from Twilio directly.
    • You can leave the To Number blank while creating the route in Notehub, and instead dynamically assign the number with a placeholder variable (see below).
  6. If the body of your SMS message will be the same every time, provide that message in the route's Message field. If the body will vary, you can provide the message dynamically using a placeholder variable (see below).

  7. After that, scroll down in Notehub to the Filters section and change the Notefiles dropdown to Selected Notefiles. Select the Notefiles you want to trigger SMS messages, or type them in the Include Other Notefiles textbox. For example, the image below shows how to select only twilio.qo Notefiles.

    Filtering by select Notefiles when creating a Twilio route

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

Customize with Placeholder Variables and JSONata

If you need to dynamically assign the To Number, From Number, or Message of the SMS, the best way to accomplish this is with placeholder variables and (optionally) a JSONata expression.

  1. Placeholder variables let you replace segments of Route settings with data from a device, event, or environment variable. In this example, we will use data elements from the body of a Note to populate the To Number, From Number, and Message of an SMS.

    {
       "device": "dev:000000000000000",
       "body": {
         "customMessage": "Hello from Notecard!",
         "customTo": "+18885551212",
         "customFrom": "+18885552121"
       }
    }
  2. In your Twilio Route settings, set the following event attribute placeholders:

    setting twilio route placeholders

  3. (Optional) You can also utilize JSONata to conditionally transform Twilio Route settings on-the-fly. For example, if you wanted to send a different message based on a DeviceUID, you could use the following JSONata expression in your Route settings:

    {
       "device": device,
       "body": {
         "customMessage": $contains(device, "dev:000000000000000" )? "It's device 0000..." : "It's NOT device 0000...",
         "customTo": body.customTo,
         "customFrom": body.customFrom
       }
    }

Testing the Route

Now that you've created a Notehub route let's look at how to test it. In this section you'll create a Notehub event that triggers your newly created route, and ultimately send yourself an SMS message.

  1. Use the In-Browser Terminal to connect to your Notecard via USB. (If you're unsure how to do this check out the Notecard quickstart.)

    Notehub.io: Web Console Button

  2. Associate your Notecard with a Notehub project using the hub.set command (if it isn't already).

    {
        "req": "hub.set",
        "product": "com.example.yourname:yourproject"
    }
    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 Notefile.

    {
        "req": "note.add",
        "file": "twilio.qo",
        "sync": true,
        "body": {
           "customMessage": "Hello from Notecard!",
           "customTo": "+18885551212",
           "customFrom": "+18885552121"
        }
    }
  4. Because the Note above contains a "sync": true attribute, the Notecard will automatically sync this Note to Notehub. Once Notehub receives the event it automatically invokes the Twilio API — and after that, you should see a notification on your device!

    Display of the Twilio SMS message on a watch

Debugging the Route

If your messages aren't being sent through Twilio as expected, navigate to the Events section in your Notehub project.

Here you'll see all events associated with your project, including the twilio.qo event you sent in the previous section. If the event failed to route to Twilio successfully you'll see an error icon for that event on the Events page.

A list of Notehub events showing one error

If you click the icon you'll see the response from the Twilio API, which often contains more information on why the request failed. For example, the error below shows what happens if you try to send a message to an invalid phone number.

A detailed look at a Notehub error

Can we improve this page? Send us feedback
© 2025 Blues Inc.
© 2025 Blues Inc.
TermsPrivacy
Notecard Disconnected
Having trouble connecting?

Try changing your 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
Use USB to connect and start issuing requests from the browser.
Try Notecard Simulator
Experiment with Notecard's latest firmware on a Simulator assigned to your free Notehub account.

Don't have an account? Sign up