Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Programmable Wireless: Narrowband IoT

Twilio and T-Mobile present Narrowband

Twilio Programmable Wireless offers a new SIM which gives access to the T-Mobile Narrowband network. Narrowband technology is designed to support Massive Internet of Things (IoT) use cases (typically low bandwidth).

On this page

Early Access Demo was shown to SIGNAL 2018 Attendees and Trusted Partners.

Alfa Developer Kit

The Developer Board provided with the Alfa Developer Kit is based on the STM32F405RG Arduino MCU series with a Narrowband U-Blox Sara-N410 cellular module. The Alfa Developer Kit ( distributed to SIGNAL 2018 attendees) includes a set of Grove sensors – humidity, light, and ultrasonic.

Alfa Developer Kits were distributed to SIGNAL 2018 conference attendees in San Francisco, CA on October 17th & 18th.

Breakout SDK

Breakout SDK enables developers to exchange data between low-powered devices and their services running in the cloud. It intends to do this in the most resource-efficient manner possible.

The first build target for the Breakout SDK is the U-Blox Sara-N410 cellular module running on the Twilio Alfa Narrowband Developer Kit. It supports the U.S. T-Mobile Narrowband network.

Currently, only the T-Mobile Narrowband network in the United States is supported.

In the future, Breakout will provide expanded device support across different cellular technologies.

Breakout SDK has the following design goals:

  • Abstract the complexity of cellular modem hardware
  • Provide access to cloud services in a resource-efficient manner (see note * below)
  • Abstracts underlying transports (e.g. IP, SMS, NIDD) (see note ** below)
  • Handles necessary cellular network registration

* During the Narrowband Pilot, a simple HTTP bridge is facilitated via the Commands API.
** During the Narrowband pilot, we are ‘approximating’ NIDD using UDP over IP. The API experience is unlikely to change in the future, but you should achieve much greater energy and network efficiency before the product and developer kit reach general availability.

Download and install the Breakout SDK

1. View the Twilio Breakout SDK for Arduino on Github

Fork the Twilio Breakout SDK for Arduino on Github. (Contributions are, of course, encouraged.)

You can follow the getting started guide ( to install in a few minutes the Breakout SDK onto your Arduino IDE. Then you can start sending and receiving Commands from the device.

Don't forget to join the Gitter channel for help, or email

2. View the Twilio Breakout SDK Environment Setup on Github

If you need help installing the Arduino IDE and other requirements to use the Breakout SDK, take a look at the file in the Twilio Breakout Arduino Library repository in Github.

See Twilio Breakout SDK for Arduino (Github) for additional documentation.

Breakout communication channels

Currently, the Breakout SDK supports only one channel for communication between devices and the outside world:


The Commands API provides simple two way short messaging for IoT devices. It enables very simple data exchanges:

  • 140 byte messages
  • Bi-directional
  • Encoded as either text or binary (text mode is GSM7 for SMS, or UTF-8 for IP)

For the Breakout SDK, two new parameters have been added to the Commands instance resource:


Always is ip when using the Breakout SDK.


Optional parameters (defaults to true), which determines if a delivery receipt was requested from the receiving party (which could be either the device or the server). While this parameter must always be set to true when using the SMS transport, for ip it can be set to true or false. Setting this to false could result in energy savings

SMS Commands versus IP-based polling Commands

Currently, the Commands API will automatically choose whether to deliver via IP (polling) for Narrowband devices or SMS for non-Narrowband devices. However, during the Narrowband Pilot, no dual-mode capable devices are provided.

What is Polling?

Polling checks the server for new Commands (updates) at predefined intervals which are no less than 60 seconds.

Why do we poll for Commands?

In the non-Narrowband world, Commands are pushed to the device over SMS.

However, in the Narrowband world (currently), the device must ask the server if any Commands are waiting. This is because the server does not tell the device that Commands are available.

In other words, polling is used because the server does not send any Commands directly to the device. The device must ask the server if any Commands are available to be sent to the device.

Prototype using the Alfa Developer Kit and Breakout SDK

The Alfa Developer Kit’s purpose is to inspire and equip developers with the necessary tools to create products using the next generation of cellular technologies for IoT.

Getting started

You can get up and running quickly by following the instructions in the Twilio Alfa Developer Kit quickstart guide.


Send/receive commands

Of course, Hello World. You can use this example to learn how to send and receive commands.

Sensor examples

Now, in the real world. After the Alfa Developer Kit is up and running, you can get started using the kit with a set of provided sensor examples:

  • Button - a simple indicator that a button has or has not been pressed
  • Ultrasonic Ranger - provides distance measurements (in cm)
  • Temperature/Humidity - sends temperature and humidity information every 10 minutes.
  • GPS - provides current latitude and longitude position

Narrowband services through Breakout SDK

Obtaining Narrowband SIMs

Narrowband SIMs were given to SIGNAL 2018 attendees and, currently, this is the only mechanisms for SIM sourcing.

After the Pilot, Narrowband SIM orders may be placed from the Console.

Registering SIMs

Received an Alfa Developer Kit with a Narrowband SIM?

Register the SIM to your Twilio account by following the normal Starter SIM registration process. If you need help, see I've got a Starter SIM for general instructions.

Narrowband SIM Rate Plans

Narrowband SIMs require a specific Rate Plan. A Narrowband Rate Plan is created when you register a Narrowband SIM.

During the Pilot, as the only available Narrowband pricing plan is the Developer Plan, this plan will be automatically added to your new Narrowband Rate Plan.

To create a Narrowband Rate Plan without going through the SIM registration process:

  1. Visit the Create a Rate Plan section of the Console
  2. Select Narrowband for SIM type
  3. Give the Rate Plan a unique name
  4. Continue through the Rate Plan creation process
  5. Click the Create button

Device to server authentication using PSKs

During the Narrowband Pilot, devices authenticate to the Breakout cloud service using Pre-Shared Keys (PSKs) over Datagram Transport Layer Security (DTLS).

PSKs can be obtained on the Breakout SDK tab of a SIM resource for any T-Mobile Narrowband SIM in the Programmable Wireless Console.

Alfa Quickstart SIM Resource Breakout

The Narrowband SIM PSK needs to be copied into your application code. In the future, Narrowband SIMs will come preloaded with the necessary tools for device identity and authentication (see Trust Onboard).

Narrowband network support

Currently, the T-Mobile Narrowband network supports the following:

  • User plane IP connectivity from the device through the packet gateway across the Internet to Twilio's servers.

This is likely to change throughout the Pilot. As such, it's important to always be running the most up-to-date version of the Breakout SDK.

SIM lifecycle

Twilio Narrowband SIMs support the same set of SIM Statuses as the non-Narrowband SIMs. However, the Narrowband Developer Plan does not support the ready state, but remember, Narrowband SIMs have a specific Rate Plan. See the next section.

Billing and metering

During the Pilot, only the Narrowband Developer Plan is supported. The Developer Plan is $2 per month and includes 2MB of data per month. Overages are billed at 50¢ per MB, metered and billing in 100KB increments.

The Developer Plan is designed to support 60 connections per hour.

Production Plans (to be released) are designed to support 10 connections per hour.


Heartbeats are sent from Breakout to Twilio:

  • When the polling interval is fired
  • When you manually check for a Command
  • When you send a Command
  • When you receive a Command

Heartbeats are registered with Breakout service and visible under the Breakout SDK tab of your Narrowband SIM Resource in Console. Heartbeats are displayed in reverse chronological order.

You will see the version of Breakout that your Developer Board is running and the date and time the Heartbeat was sent.

Connection limiting

Narrowband is optimized for low bandwidth devices that transmit data infrequently, aka "Massive IoT" devices.

As such, there are limits on the number of messages that you can send or receive on the T-Mobile Narrowband network. There is no hard 'cap' applied for these limits. However, T-Mobile reserves the right to automatically or manually disable devices that behave beyond the reasonable limits set forth:

  • A 'connection', in the context of IP, is synonymous to an IP packet
  • Packets over 1500 bytes will count as two connections
  • Packets over 3000 bytes will count as three connections.
  • And so forth

When using the Commands service together with the Breakout SDK, you can expect the following:

Command Count
Everytime I send or receive a Command. 1 connection
Everytime a Command delivery receipt is sent or received. 1 connection

Scenario 1

A Command is sent or received from the device with no receipt requested. This counts as 1 connection.

Command Count
A Command is sent from the device. 1 connection
Total 1 connection

Scenario 2

A Command is received from the server with a receipt requested. This counts as 2 connections.

Command Count
A Command is sent to the device. 1 connection
A receipt acknowledging the delivery of the Command is sent from the device to the server. 1 connection
Total 2 connections

Scenario 3

A Command is sent and a receipt is requested. This counts as 2 connections.

Command Count
A Command is sent from the device. 1 connection
A receipt acknowledging the delivery of the Command is sent from the server to the device. 1 connection
Total 2 connections

Frequently Asked Questions (FAQ)

Is the Super SIM related to the Narrowband SIM?

  • Not today. Today the Super SIM is designed to support 2G, 3G and LTE.

Is Narrowband available on the same SIM we sell today?

  • No. A separate physical SIM is required for Narrowband.

How much data do I get per month during the Pilot?

  • 2MB per month.

How many Commands can I send using Breakout SDK during the Pilot?

  • There are no limit to the number of Commands that you can send and receive.

How much do Commands cost during the Pilot?

  • Commands delivered to Narrowband devices using the IP transport (not SMS) are free during the Pilot.

Will my Narrowband SIM work with Programmable Voice?

  • No. Narrowband IoT (the underlying radio technology) does not support voice.

Will my Narrowband SIM work with Programmable SMS?

  • No. Narrowband is not in any way designed for communications use cases.

What type of hardware is required for a Narrowband SIM?

Can I use any Narrowband cellular module device?

  • No. Cellular modules must be certified by the T-Mobile network to be used in devices. Visit the Device Certification section for more information.

Geographically, where can I use my Alfa Developer Board?

  • T-Mobile's Narrowband network is deployed in the U.S. only.

How can I order a SIGNAL 2018 Alfa Developer Kit?

  • Alfa Developer Kit’s are not for sale in Console. Alfa Developer Kits were distributed to SIGNAL 2018 conference attendees in San Francisco, CA on October 17th & 18th.
  • If you have a use case you'd like to prototype during the Pilot, please Talk to Sales. Developer Kits will be released for general sale at the conclusion of the Pilot.

How can I order a Narrowband SIM?

  • Narrowband SIMs are not currently available for order in Console during the Pilot. Talk to Sales.

How do I create a Rate Plan for Narrowband SIMs?

Can I use an existing Rate Plan with Narrowband SIMs?

Device certification (for production)

Any product utilizing the T-Mobile Narrowband network that is intended for commercialization will need to be certified by T-Mobile.

Since the Alfa Developer Kit uses a T-Mobile certified module (the U-Blox N410B), most of the heavy lifting for certification has already been completed for you, assuming you continue to use the same module.

As the OEM/Product Developer, you will need to provide T-Mobile with device capability information.

Certification requirements include security certification, 'Safe For Network' testing, and delta certification for PTCRB. T-Mobile will also onboard the device to their Device Management platform, which today is handled for you by the Alfa Developer Kit.

Fast path to certification:

  • Use a T-Mobile pre-certified module

Required certifications and tests:

  • Module certification completed through T-mobile
  • PTCRB of the product completed
  • Device Security (CTIA) test plan
  • Device Management verified through T-mobile
  • Safe for Network (T-Mobile)
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.