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: Twilio SIM Setup in a Nutshell

Preparing a Twilio SIM for use is straightforward, but it necessarily involves some terminology and concepts that you may be unfamiliar with. This page will fix that.

SIM essentials

SIM stands for Subscriber Identification Module. A SIM essentially tells a mobile device which cellular networks it can connect to and authorizes the device’s attempts to connect to those networks.

Any device that wants to connect to a cellular network must contain a SIM.

Access Point Names

Devices send and receive data over a cellular network through what is called an ‘Access Point’. Think of it as the gateway through which all of the device’s cellular data flows. To transfer data, the device has to know this server‘s identity, ie. the Access Point Name (APN).

Once you’ve fitted a Twilio Programmable Wireless SIM into a device, you need to tell the device what APN to use. Twilio has two APNs for Programmable Wireless SIMs: and iot.nb, for the Broadband IoT and Massive IoT SIMs, respectively. Which one you select will depend on the type of SIM you have; how you enter it will depend on the type of device you’re using.

Check out Cellular Network Configuration to find out the correct APN to use, and how to feed it into your device.

Rate Plans

Twilio Rate Plans are configurations which specify SIM capabilities. Before you can use a Programmable Wireless SIM, you will need to set up a Rate Plan and assign the SIM to it. The SIM is then able to determine what it’s allowed to do:

  • What kind of cellular network technologies it can use, eg. 4G or Narrowband.
  • What mix of data, voice and messaging services it supports.
  • What alternative networks it can roam onto if it needs to, if any, and whether roaming can take place only in the US or internationally.
  • What kind of payment plan a SIM‘s data billing is governed by.
  • What limits you wish to place on how much data the SIM allows the host device to transfer each month.

Rate Plans are created and configured in the Console. It’s easy to do: you just follow a series of five simple steps. You also use the Console to associate one or more of your SIMs with a Rate Plan.

Every one of your SIMs must be associated with a Rate Plan, but a Rate Plan can be associated with any number of SIMs. How many Rate Plans you use depends solely on your use case.

You should read Understanding Rate Plans to learn how to create and apply new Rate Plans.

SIM states

Twilio SIMs exist in one of eight possible states; a SIM’s status indicates the state it is currently in. You can view a SIM’s status in the Console or by making a call to the Programmable Wireless API. These interfaces allow you to change a SIM’s state too, though some states are also entered automatically. For example, when you update a SIM’s status, it automatically enters the Updating state and, upon completion, moves to the state you chose.

You may not feel the need to change your first SIM’s state, but the ability to move SIMs from one state to another state gives you a great deal of control over devices in the field. For example, it allows you to temporarily disable devices which may have been lost or stolen. If a missing device shows up, you can return it to an operational state; if it stays missing, it will be canceled 72 hours after it was disabled. Once canceled, the SIM can never be used again.

To be fully operational, all SIMs need to enter the active state, and that’s one of the outcomes of the SIM registration process you run through with individual SIMs (bulk-bought SIMs are registered for you).

To learn about the various states a SIM can enter, what they mean for its capabilities, and how they can be used to manage devices in the field, take a look at Understanding SIM states.

SIM activation

A new SIM can’t connect to the cellular network until it has been added to your account and activated. That means entering its registration code (printed on card the SIM comes mounted to) into the Console and assigning it to a Rate Plan.

At this point the SIM is in the Ready state; it’s allowed to connect to the network and transfer data. After three months, 250KB of transferred data, or five commands have been sent to or sent from the SIM, whichever comes first, it transitions to the Active State and you will be billed according to the data it transfers.

You can read all about wireless data pricing here.

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.