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.

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