Twilio Event Streams is an API that allows you to tap into a unified stream of interactions across different Twilio products. You can stream your data to your existing systems by configuring a modern, persistent streaming technology like Amazon Kinesis, or to a webhook.
Super SIM Connection Events allow you to follow a Super SIM connected device's journey from when Twilio first sees it trying to connect to our mobile core, to when it gets connected and starts to use data, to when it ends its data session. Once a device has successfully started a data session, update events will be published while the device stays connected to give you near real-time usage information for each Super SIM.
Every Super SIM Connection Event will be one of a set of specific event types. These event types are described below and use the same schema.
The Amazon Kinesis Quickstart and Webhook Quickstart pages can help you get started with the Event Streams API. Helper libraries are also available for popular programming languages to help you quickly integrate Event Streams into your code.
Connection Events may be published every time your device attempts to connect to the cellular network. Before subscribing to Super SIM Connection Events, you should first review each of the event types described below and the Event Stream pricing. We've included some tips and tricks for getting started with Super SIM Connection Events to minimize costs can be found at the end of this page.
Currently, there are six types of event which may be emitted into the stream:
This flowchart shows when these events may be triggered once a device has powered up:
Event type string: com.twilio.iot.supersim.connection.attachment.accepted
Your device successfully authenticated with a cellular network and is allowed to connect to it. This means:
ready
or
active
.
If your device is using a valid Super SIM APN (e.g., super
) and the device is able to establish a data connection, a Data Session Started event will follow this event. If you receive repeated attachment.accepted
events in quick succession, it may indicate that the device is unable to use data and is repeatedly restarting the attachment process.
This event may not be published every time your device connects. For instance, it will not be published if the device has previously authenticated with the network, which has cached the device's permission.
Event type string: com.twilio.iot.supersim.connection.attachment.rejected
Your device's attachment request was rejected by the network. The device was unable to connect.
Rejections can occur because:
new
or
inactive
.
To connect, your device will need to try a different network, use a different IMSI, or retry after the Network Access Profile used by the Super SIM's Fleet has been updated to allow the network.
Your devices may aggressively try to connect to all of the cellular networks visible to them. An attachment.rejection
event will be published for each of these attempts if Twilio receives the attachment request from the cellular network. To understand how rapidly your device will create attachment.rejection
events if it is unable to connect, you can use this tip. Make sure you review the Event Stream pricing before subscribing to this event type for all of your devices.
Event type string: com.twilio.iot.supersim.connection.attachment.failed
Your device's attachment request failed for an unknown reason.
This event usually indicates a transient error which will resolve itself in time. When the device attempts to reconnect to the network, it may get a different result.
Event type string: com.twilio.iot.supersim.connection.data-session.started
Your device is connected to a network using a valid Super SIM APN, and can send and receive data.
Data session events will be published for traffic on both user APNs (e.g., super
) and OTA APNs (e.g., ota.super
) because all data used is billed and counts towards the Super SIM's data limit. However, data-session.started
events will not indicate how much data was transferred by a device; this event only indicates that a data session has begun. To track data usage, subscribe to Data Session Updated events.
Event type string: com.twilio.iot.supersim.connection.data-session.updated
Your device has remained connected using a valid Super SIM APN, and can continue to send and receive data.
While the device remains connected, data-session.updated
events will be published approximately every six minutes, with the first arriving approximately six minutes after the Data Session Started event. Each data-session.updated
event will include the number of bytes that were sent to the device (the event's data_download
property) and the number sent by the device (data_upload
) between the data_session_update_start_time
and the data_session_update_end_time
.
If your device is designed to maintain a persistent network connection, you should expect approximately 10 data-session.updated
events per connected device per hour — they are published every six minutes. This could exceed 7,000 data-session.updated
events per month per device, so please ensure that you have reviewed the Event Stream pricing.
Event type string: com.twilio.iot.supersim.connection.data-session.ended
Your device's data session has ended. The device can no longer send or receive data until a new data session is started. This event will include the amount of data that was sent to the device (data_download
) and from the device (data_upload
) since the most recent Data Session Updated event.
The data_session_start_time
, data_session_end_time
, data_session_data_download
, data_session_data_upload
, and data_session_data_total
properties can give you a complete picture of the data session, telling you how long the device's data session was maintained and how much data was exchanged over it.
Event type string: com.twilio.iot.supersim.connection.data-session.failed
Your device's attempt to create or maintain a data session failed. The device can no longer send or receive data until a new data session is started.
The Super SIM events you receive are based on a common schema that defines the following properties. Some properties will not be present in every case: error
will not be included if no error took place, and attachment-related events will not include data-related properties. The data_modifier
property is only included if the Super SIM has exceeded its data limit. The location
and imei
properties will be omitted if Twilio didn't receive this information from the visited network.
If your subscription is not using the latest version of the Connection Events schema, some fields may be missing.
Property | Description |
---|---|
event_sid | The event's SID. This is a copy of the ce_id header field. |
event_type | The type of connection event. This is a copy of the ce_type header field. |
timestamp | The UTC time in ISO8601 format when the event occurred. |
account_sid | The SID of the Account that the Super SIM and this record relate to. |
apn | The Access Point Name (APN) used to establish a data session. |
data_modifier | Indicates if the Super SIM's data usage is blocked because the SIM has reached its data limit. Its value will be blocked if data use is blocked, or null if data usage is not blocked. |
data_session_sid | A unique string ID identifying a data session. |
data_session_start_time | The data session UTC start time in ISO8601 format. |
data_session_end_time | The data session UTC end time in ISO8601 format. |
data_session_update_start_time | The data session UTC update start time in ISO8601 format. For a data-session.updated or data-session.ended event, this time indicates the start of the window for which the update was published. The data usage values included with these events was consumed between this time and the data_session_update_end_time . |
data_session_update_end_time | The data session UTC update end time in ISO8601 format. For a data-session.updated or data-session.ended event, this time indicates the end of the window for which the update was published. The data usage values included with these events was consumed between the data_session_update_start_time and this time. |
data_download | The amount of data downloaded to the device in bytes between the data_session_update_start_time and data_session_update_end_time . |
data_upload | The amount of data uploaded from the device in bytes between the data_session_update_start_time and data_session_update_end_time . |
data_total | The total amount of data uploaded or downloaded by the device in bytes between the data_session_update_start_time and data_session_update_end_time . The sum of data_download and data_upload . |
data_session_data_download | The cumulative amount of data downloaded to the device over the data session. The cumulative amount of data downloaded to the device in bytes between the data_session_start_time and data_session_update_end_time or data_session_end_time for data-session.ended events. |
data_session_data_upload | The cumulative amount of data uploaded by the device over the data session. The cumulative amount of data uploaded by the device in bytes between the data_session_start_time and data_session_update_end_time or data_session_end_time for data-session.ended events. |
data_session_data_total | The cumulative amount of data uploaded or downloaded by the device over the data session. The cumulative amount of data uploaded or downloaded by the device in bytes between the data_session_start_time and data_session_update_end_time or data_session_end_time for data-session.ended events. The sum of data_session_data_download and data_session_data_upload . |
imei | The International Mobile Equipment Identity of the device using the Super SIM to connect. This may be null as it is not guaranteed that the visited network will pass on this information. |
imsi | The International Mobile Subscriber Identity used by the Super SIM to connect. |
ip_address | The IP address assigned to the device. This address is not publicly addressable. |
sim_iccid | The Integrated Circuit Card Identification Number of the Super SIM this record relates to. |
sim_sid | The Super SIM's SID. |
sim_unique_name | The Super SIM's unique name. |
fleet_sid | The SID of the Fleet to which the Super SIM is assigned. |
location | An object containing information about the location of the cell to which the device was connected. This may be null as location information is not guaranteed to be sent by the visited network. See Location info properties for more details. |
network | An object containing information about the network that the Super SIM attempted to connect to or is connected to. See Network info properties for more details. |
rat_type | The generation of wireless ('radio access') technology that the device was using. This will be one of: 2G , 3G , or 4G LTE . |
error | An object containing information about any error encountered. See Error info properties for more details. |
The event's location
property provides information about the placement of the cell tower to which the device was or is connected. This information is not guaranteed to be send by the network, so this property may be null
.
Property | Description |
---|---|
cell_id | The unique ID of the cell tower that the device was attached to. |
lac | The location area code (LAC) of the cell tower. |
lat | The tower's estimated latitude. |
lon | The tower's estimated longitude. |
The event's network
property contains information about the visited cellular network that the device attempted to connect to or is connected to.
Property | Description |
---|---|
mcc | The Mobile Country Code (MCC) of the network that the Super SIM attempted to connect to or is connected to. |
mnc | The Mobile Network Code (MNC) of the network that the Super SIM attempted to connect to or is connected to. |
friendly_name | The human-readable name of the network to which the MCC-MNC values belong. |
iso_country | The network's ISO2 country code. |
sid | The SID of the Network resource representing the network. |
The event's error
property will be null
if no error occurred. Otherwise it contains the following information.
Property | Description |
---|---|
code | A Twilio error code. |
message | A short message indicating why the error occurred. It may include standard [Diameter protocol](https://en.wikipedia.org/wiki/Diameter_(protocol\)) error messages. |
If you already have a number of devices deployed, you may quickly exceed the first 100,000 free events offered by Event Streams. For example, data-session.updated
events are published every six minutes if your devices maintain a persistent connection, and can therefore exceed 7,000 events per device per month. We recommend you start your development work in a separate Twilio Subaccount or Project so you don't get charged for the events generated by all of your devices until you are ready.
You can transfer a Super SIM that is still in the new
state to a subaccount by using this API request. If you wish to transfer a Super SIM in another state to a different Account (either a Subaccount or a Project), please open a support ticket. A Twilio Support Specialist will be able to help you get started.
To generate attachment.rejected
events, you can put a Super SIM that is either new
or inactive
into your device. Alternatively, update your Fleet's Network Access Profile to block all of the networks in your country.
If you don't need to do near real-time usage billing or metering, you may be able to use data_session_data_upload
, data_session_data_download
, or data_session_data_total
properties on data-session.ended
events to understand how much data each of your devices are using without having to subscribe to data-session.updated
events. These fields contain the cumulative amount of data exchanged by your device over the data session. This can reduce the number of events you have to receive and process by over 90%.