メニュー

Expand
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?

How to Determine a Super SIM’s Status

Every Sim resource will be in one of five possible states, each of which indicates a Super SIM’s authority to connect to the cellular network while in that state. Some states are achieved automatically; others can be set by changing the Sim resource’s status property. This guide will describe each of the states and show you how a Sim resource enters them. It will also detail some common scenarios in which you may want or need to change a Sim resource’s state.

Sim resource states

At any given moment, a Sim resource will be in one of the following states:

  • new
  • ready
  • active
  • inactive
  • scheduled

The resource’s status property will tell you to which of these states it is currently set — and therefore whether the Super SIM represented by the resource is able to allow its host device to access the network. The value of status is a string matching one of the states listed above.

Changing a Sim resource’s state doesn’t change the Super SIM it represents in any way, but simply governs whether partner networks permit that Super SIM to access network resources.

So what do these states represent exactly?

State Meaning
new The Sim resource has never been activated, and the represented Super SIM can’t connect to the network. A Sim resource can remain in new indefinitely at no charge. Once it has transitioned to ready or active, it can’t be returned to new
ready The Sim resource's Super SIM can connect to the network and is capable of consuming network resources in accordance with the configuration of the Fleet resource to which it has been assigned (indicated by the Sim resource’s fleet_sid property), but no monthly subscription fee will be charged.

A Sim resource’s status can only be switched to ready if it currently new. Once a ready Super SIM has consumed 250KB of data, five SMS Commands have been sent or received by the Super SIM, or three months have passed, the Sim resource’s state will automatically transition to active.

Use ready to enable and test your connectivity without incurring monthly fees before devices are sent to customers or deployed into the field
active The Sim resource’s Super SIM can connect to the network and is capable of consuming network resources in accordance with the configuration of the Fleet resource to which it has been assigned (indicated by the Sim resource’s fleet_sid property)
inactive The Sim resource’s Super SIM is blocked from connecting to the network. The Sim resource can be switched to active at any time. A Sim resource can remain in inactive indefinitely at no charge
scheduled A request top update the Sim resource’s state is queued and will be processed asynchronously. The value of status will automatically transition to the requested state when the update operation has completed

Fleets are how Sims are organized into groups. All the Sims in a Fleet behave the same way: how their data usage is billed and whether they accept Commands. Rather than apply these settings to each Sim individually, you just update the Fleet, and all the Sims in that Fleet automatically adopt the new configuration.

Active Super SIMs

When a Sim resource’s status is ready or active, its Super SIM can be used by a device to connect to the network and transfer data. In fact, it must be set to ready or active in order to be able to connect.

Once active, the Sim resource can be manually transitioned to inactive only by specifying that as its new state. The resource’s status will initially be set to scheduled. The change to the requested state is made asynchronously, and the resource’s status property will only show the desired value when the update has actually been applied:

When you update a Sim resource, you can include a callback URL (as the value of the query parameter CallbackUrl). If the Sim resource's update is handled asynchronously, this callback URL will be sent notifications when the target resource’s status actually changes (first to scheduled, then to the requested value). The callback URL is used for this requested change only; it is not applied as a global setting. If the Sim resource's update is completed synchronously, no notification will be sent to the callback URL.

The following diagram shows how this asynchronous behavior operates over time:

How to check a Sim’s status

Please see the Sim resource documentation to learn how to request Sim resources. The value of the resource’s status property will tell you its current state. For example, if you request a Sim resource using curl:

curl -X GET \
    https://supersim.twilio.com/v1/Sims/<SIM_SID> \
    -u <YOUR_ACCOUNT_SID>:<YOUR_AUTH_TOKEN>

The response returns the Sim resource as JSON:

{ "sid": "<SIM_SID>",
  "account_sid": "<YOUR_ACCOUNT_SID>",
  "unique_name": "My SIM",
  "status": "new",
  "fleet_sid": null,
  "iccid": "<THE_SIM_ICCID>",
  "date_created": "2015-07-30T20:00:00Z",
  "date_updated": "2015-07-30T20:00:00Z",
  "url": "https://supersim.twilio.com/v1/Sims/<SIM_SID>" }

As you can see, this Sim has not yet been activated — its status is new — and it has not yet been assigned to a Fleet: the fleet_sid property is null.

You can also view a Super SIM’s status in the Console, under the STATUS column of the SIMs list.

How to change a Sim’s status

You can change a Sim resource’s status by making a POST request to the API. In the request’s URL-encoded query parameters, you include Status — its value is the state to which you want the Sim to transition. For example:

curl -X POST \
    https://supersim.twilio.com/v1/Sims/<SIM_SID> \
    --data-urlencode "Status=<NEW_STATE>" \
    -u <YOUR_ACCOUNT_ID>:<YOUR_AUTH_TOKEN>

Please see the Sim resource documentation to learn what other fields you can include. As noted earlier, it’s a good idea to include the URL of an endpoint on your own server to which state-change notifications will be sent. Here’s a fictional URL to show you how it’s done:

curl -X POST \
    https://supersim.twilio.com/v1/Sims/<SIM_SID> \
    --data-urlencode "Status=<NEW_STATE>" \
    --data-urlencode "CallbackUrl=https://example.com/api/v1/notifications" \
    -u <YOUR_ACCOUNT_ID>:<YOUR_AUTH_TOKEN>

The only states that a Sim resource can be manually instructed to change to are ready, active, and inactive. Once it is no longer new or ready, a Sim resource can never return to that state (see the first diagram above). The scheduled state is only ever set automatically, and briefly, in response to your own state-change requests.

When to change a Sim’s state

You will transition a fresh Super SIM from new to ready or active (via scheduled) when you fit it into a device, configure the device’s Access Point Name (APN) setting, and connect to the network.

Transition the Sim to ready (rather than active) if you are using the Super SIM it represents for testing and would prefer not to incur monthly fees. Once the Sim has consumed 250KB of data, five SMS Commands have been sent or received by the Super SIM, or three months have passed, its state will automatically transition to active. Or you can switch it to active manually earlier.

If you have a Super SIM that you want to stop using for an extended period, so that it does not incur charges, just set its Sim resource’s status to inactive: send a POST request to the API and set the Status parameter’s value to inactive. For example:

curl -X POST \
    https://supersim.twilio.com/v1/Sims/<SIM_SID> \
    --data-urlencode "Status=inactive" \
    -u <YOUR_ACCOUNT_ID>:<YOUR_AUTH_TOKEN>

When you’re ready to use the SIM again, simply reactivate it: just send a POST request to the API and this set the Status parameter’s value to active:

curl -X POST \
    https://supersim.twilio.com/v1/Sims/<SIM_SID> \
    --data-urlencode "Status=active" \
    -u <YOUR_ACCOUNT_ID>:<YOUR_AUTH_TOKEN>

An inactive Sim resource can only reconnect if it is moved back into the active state, and this can only be achieved through the API, as shown above, or the Console, under your account credentials.

If a physical Super SIM is lost or stolen, switch it to inactive as soon as possible to prevent its use. An inactive Super SIM is blocked from connecting to the network.

Rate this page:

ヘルプが必要ですか?

誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。