---
title: Configuring a Twilio Route
description: A guide to creating a Notehub route to Twilio SMS messaging services using Blues Notecard over Cellular, Satellite, LoRa, or WiFi connectivity.
source_url: https://dev.blues.io/notehub/messaging-and-data-pipelines/configuring-a-twilio-route/
canonical_url: https://dev.blues.io/notehub/messaging-and-data-pipelines/configuring-a-twilio-route/
markdown_url: https://dev.blues.io/notehub/messaging-and-data-pipelines/configuring-a-twilio-route.md
---

# Configuring a Twilio Route

[Notehub.io](https://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](https://dev.blues.io/quickstart/notecard-quickstart.md).)
- A [Twilio account](https://www.twilio.com/), with at least one [**Verified Caller ID**](https://support.twilio.com/hc/en-us/articles/223180048-Adding-a-Verified-Phone-Number-or-Caller-ID-with-Twilio) 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](https://dev.blues.io/images/guides/route-guides/notehub-add-route.png?v=50497ee1)

2. Select the **Twilio** route type.

   ![The Twilio route type in Notehub](https://dev.blues.io/images/guides/route-guides/twilio-route.png?v=61424d59)

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

   ![Location of the route name in Notehub](https://dev.blues.io/images/guides/route-guides/twilio-route-name.png?v=a4ad753b)

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

   ![How to provide Twilio data in a Notehub route](https://dev.blues.io/images/guides/route-guides/twilio-route-config.png?v=22deecf3)

5. Next, you'll need to give your route a **From Number**, which controls the phone number your message is sent *from*, and must be a valid Twilio Phone Number. See [How to Search for and Buy a Twilio Phone Number](https://help.twilio.com/articles/223135247-How-to-Search-for-and-Buy-a-Twilio-Phone-Number-from-Console) on the Twilio documentation for more information.

6. After that, 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** 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](https://www.twilio.com/docs/glossary/what-e164), which it will be if you copy/paste from Twilio directly.
   > - Instead of a static phone number, you can supply a [placeholder variable](https://dev.blues.io/notehub/notehub-walkthrough.md#using-placeholder-variable-substitution-interpolation) (for example, `[body.customTo]`) so that each SMS is sent to a number drawn from the event data ([see below](https://dev.blues.io/notehub/messaging-and-data-pipelines/configuring-a-twilio-route.md#customize-with-placeholder-variables-and-jsonata)).

7. Provide a value for the route's **Message** field, which is the body of the SMS that Twilio will send. The **Message** field is required: if the body will be the same every time, type the static message directly into the field; if the body will vary per event, use a [placeholder variable](https://dev.blues.io/notehub/notehub-walkthrough.md#using-placeholder-variable-substitution-interpolation) such as `[body.customMessage]` so the message text is drawn from the event data at routing time ([see below](https://dev.blues.io/notehub/messaging-and-data-pipelines/configuring-a-twilio-route.md#customize-with-placeholder-variables-and-jsonata)).

8. 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](https://dev.blues.io/images/guides/route-guides/twilio-filtering.png?v=33bb112c)

9. 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](https://dev.blues.io/notehub/notehub-walkthrough.md#using-placeholder-variable-substitution-interpolation) and (optionally) a [JSONata expression](https://dev.blues.io/guides-and-tutorials/notecard-guides/using-jsonata-to-transform-json.md).

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.

   ```json
   {
      "device": "dev:000000000000000",
      "body": {
        "customMessage": "Hello from Notecard!",
        "customTo": "+18885551212",
        "customFrom": "+18885552121"
      }
   }
   ```

2. In your Twilio Route settings, set the following [event attribute placeholders](https://dev.blues.io/notehub/notehub-walkthrough.md#event-attribute-placeholders):

   ![setting twilio route placeholders](https://dev.blues.io/images/guides/route-guides/twilio-placeholders.png?v=9ce64616)

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](https://dev.blues.io/guides-and-tutorials/notecard-guides/using-jsonata-to-transform-json.md) in your Route settings:

   ```jsonata
   {
      "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](https://dev.blues.io/quickstart/notecard-quickstart.md).)

   ![Notehub.io: Web Console Button](https://dev.blues.io/images/guides/route-guides/notecard-web-console-button.png?v=25006268)

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

   ```json
   {
       "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.

   ```json
   {
       "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](https://dev.blues.io/images/guides/route-guides/sms-note.jpg?v=1ddef897)

## 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](https://dev.blues.io/images/guides/route-guides/notehub-twilio-events.png?v=3992c4e7)

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](https://dev.blues.io/images/guides/route-guides/notehub-twilio-error.png?v=133c3926)