Super SIM's IP Commands API is currently in Public Beta . Some features are not yet implemented and others may be changed before the product is declared as Generally Available. Beta products are not covered by a Twilio SLA . Learn more about beta product support.
IP Commands enable you to exchange IP/UDP messages between your cloud and your devices connected with Super SIM.
https://supersim.twilio.com/v1/IpCommands
You can use IP Commands to send server-initiated IP messages from your cloud to your devices. The private IP addresses assigned to Super SIMs are behind the cellular networks' NAT/firewalls and you cannot reach them over IP without your device first initiating the connection or maintaining a persistent connection. IP Commands allow you to reach your devices over IP, by forwarding a UDP message to a port on your device and going around the networks' NAT/firewalls.
IP Commands are an alternative to using VPN to reach a device from outside the cellular network.
You can also send a UDP message from your device to a dedicated Twilio IP address that will treat the message as an IP Command from the SIM, the payload of which will be forwarded to your cloud via a webhook.
To use IP Commands, you must have data enabled on the Fleet resource your Super SIM is assigned to, and the Sim resource representing your Super SIM must be Active or Ready.
If you'd like to try IP Commands out straight away, check out our Get Started guide. Or read on for the full API documentation.
IP Commands are sent by making a POST
request to the IP Commands API. The IP Command will be sent to the device asynchronously on an existing data connection. The IP Command resource's status is updated to sent
when the IP message is sent to the device. If the device is not attached, the IP Command will not be sent and its status will be marked as failed
. An error code will be indicated on the resource.
If the device is sleeping (3GPP IDLE
mode), IP Commands can still be delivered to the device. There are three scenarios here:
You can receive IP Commands from the device by configuring a webhook on your Super SIM's Fleet resource. A special destination address, 100.64.0.1
, has been exposed by Twilio to receive IP packets. Any IP message sent to this address by your device will be treated as an IP Command and the content will be delivered to your Fleet resource's ip_commands_url
.
To receive a Command (Mobile Originated) from a SIM, you should create or update an existing Fleet instance and provide an ip_commands_url
property and, optionally, an ip_commands_method
property.
When a SIM sends an IP message to the special IP address 100.64.0.1
, an IP Command resource will be created and your ip_commands_url
will be invoked. The callback request will include the same parameters as the IP Commands status callbacks.
The IP Command resource performs asynchronous operations. To receive an asynchronous notification when a IP Command resource has finished updating, provide a callback URL, and optionally a callback method parameter, when you create the IP Command.
IP Commands are retained for 30 days from the time they are created. IP Commands older than 30 days will no longer be readable from this resource.
Customers may request that IP Command data be deleted. If you wish to do so, please contact Twilio Support through the Console or Help Center. For more information on Twilio's data retention and deletion policy, please see this support document.
The unique string that we created to identify the IP Command resource.
^HG[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The SID of the Account that created the IP Command resource.
^AC[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The SID of the Super SIM that this IP Command was sent to or from.
^HS[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The delivery status of the IP Command. This is one of the following: “queued”, “sent”, “failed” or “received”.
queued
sent
received
failed
Either to_sim
or from_sim
. Indicates whether the IP Command resource was sent from or to the Super SIM.
to_sim
from_sim
The IP address of the device that the IP Command was sent to or received from. For an IP Command sent to a Super SIM, device_ip
starts out as null
, and once the IP Command is “sent”, the device_ip
will be filled out. An IP Command sent from a Super SIM have its device_ip
always set.
For an IP Command sent to a Super SIM, it would be the destination port of the IP message. For an IP Command sent from a Super SIM, it would be the source port of the IP message.
0
Either “text” or “binary”. For an IP Command sent to a Super SIM, payload_type
is configurable. For an IP Command sent from a Super SIM, payload_type
is always “binary”.
text
binary
The payload that is carried in the IP/UDP message. The payload can be encoded in either text or binary format. For text payload, UTF-8 encoding must be used.
For an IP Command sent to a Super SIM, the payload is appended to the IP/UDP message “as is”. The payload should not exceed 1300 bytes.
For an IP Command sent from a Super SIM, the payload from the received IP/UDP message is extracted and sent in binary encoding. For an IP Command sent from a Super SIM, the payload should not exceed 1300 bytes. If it is larger than 1300 bytes, there might be fragmentation on the upstream and the message may appear truncated.
The date and time in GMT when the resource was created specified in ISO 8601 format.
The date and time in GMT when the resource was last updated specified in ISO 8601 format.
The absolute URL of the IP Command resource.
The table below describes the available status values of an IP Command resource instance. When the API is called to send an IP message to your device, the returned IP Command resource's status will be queued. The status property will be updated to sent when an IP message is sent to the visited cellular network to which your device is connected. If at any point this process fails, and the IP Command is not deliverable, the status property will be updated to failed
and an error code will be indicated on the resource.
queued | The IP Command was accepted and is queued in our service waiting to be sent. |
---|---|
sent | The IP Command was sent to the SIM in the form of an IP message. |
received | The IP Command was received from the SIM. |
failed | The IP Command could not be sent. |
The user can provide a callback method and callback URL to receive updates each time an IP Command's status changes. The data included is as follows:
AccountSid | The SID of the Account that created the Command resource. |
---|---|
CommandSid | The unique string that was created to identify the Command resource. |
SimSid | The SID of the SIM that this Command was sent to or from. |
SimUniqueName | The Unique Name of the Super SIM that this Command was sent to or from. |
PayloadType | The type of payload in the IP Command. There are two possible values, text or binary , for mobile-terminated IP Commands. For mobile-originated IP Commands, PayloadType is always set to binary . |
Payload | The data that was sent or received from the device. The payload cannot exceed 1300 bytes. If the PayloadType is set to text , the payload is encoded in UTF-8. If PayloadType is set to binary , the payload is encoded in Base64. For mobile-originated IP Commands, the payload is always encoded in Base64. |
Direction | Indicates whether it is an mobile terminated or mobile originated Command. It has two possible values: to_sim or from_sim . |
Status | The delivery status of the Command. Applicable statuses for IP Commands are queued , sent , and failed . See Status values for more information. |
ErrorCode | The error code, if any, associated with your Command. Unless the status is failed , ErrorCode will not be present. |
ErrorMessage | Description of the error. Unless the status is failed , ErrorMessage will not be present. |
The following scenarios will return a synchronous 4xx error:
active
nor
ready
.
The following scenarios will result in the IP Command initially being accepted and an IP Command resource created, but they will ultimately fail. A failed
status callback will be sent to your callback_url
if one was provided in your create request:
POST https://supersim.twilio.com/v1/IpCommands
application/x-www-form-urlencoded
The data that will be sent to the device. The payload cannot exceed 1300 bytes. If the PayloadType is set to text, the payload is encoded in UTF-8. If PayloadType is set to binary, the payload is encoded in Base64.
Indicates how the payload is encoded. Either text
or binary
. Defaults to text
.
text
binary
The URL we should call using the callback_method
after we have sent the IP Command.
The HTTP method we should use to call callback_url
. Can be GET
or POST
, and the default is POST
.
GET
POST
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createIpCommand() {11const ipCommand = await client.supersim.v1.ipCommands.create({12devicePort: 42,13payload: "Payload",14sim: "Sim",15});1617console.log(ipCommand.sid);18}1920createIpCommand();
1{2"sid": "HGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"sim_iccid": "89883070000123456789",6"status": "queued",7"direction": "to_sim",8"device_ip": "100.64.0.123",9"device_port": 42,10"payload_type": "text",11"payload": "Payload",12"date_created": "2015-07-30T20:00:00Z",13"date_updated": "2015-07-30T20:00:00Z",14"url": "https://supersim.twilio.com/v1/IpCommands/HGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"15}
GET https://supersim.twilio.com/v1/IpCommands/{Sid}
The SID of the IP Command resource to fetch.
^HG[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchIpCommand() {11const ipCommand = await client.supersim.v112.ipCommands("HGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.fetch();1415console.log(ipCommand.sid);16}1718fetchIpCommand();
1{2"sid": "HGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"sim_iccid": "89883070000123456789",6"status": "queued",7"direction": "to_sim",8"device_ip": "100.64.0.123",9"device_port": 100,10"payload_type": "text",11"payload": "checkin: firmware update",12"date_created": "2015-07-30T20:00:00Z",13"date_updated": "2015-07-30T20:00:00Z",14"url": "https://supersim.twilio.com/v1/IpCommands/HGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"15}
GET https://supersim.twilio.com/v1/IpCommands
The SID or unique name of the Sim resource that IP Command was sent to or from.
The status of the IP Command. Can be: queued
, sent
, received
or failed
. See the IP Command Status Values for a description of each.
queued
sent
received
failed
The direction of the IP Command. Can be to_sim
or from_sim
. The value of to_sim
is synonymous with the term mobile terminated
, and from_sim
is synonymous with the term mobile originated
.
to_sim
from_sim
How many resources to return in each list page. The default is 50, and the maximum is 1000.
1
Maximum: 1000
The page token. This is provided by the API.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listIpCommand() {11const ipCommands = await client.supersim.v1.ipCommands.list({ limit: 20 });1213ipCommands.forEach((i) => console.log(i.sid));14}1516listIpCommand();
1{2"meta": {3"first_page_url": "https://supersim.twilio.com/v1/IpCommands?Status=received&Sim=HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",4"key": "ip_commands",5"next_page_url": null,6"page": 0,7"page_size": 50,8"previous_page_url": null,9"url": "https://supersim.twilio.com/v1/IpCommands?Status=received&Sim=HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0"10},11"ip_commands": [12{13"sid": "HGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",14"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",15"sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",16"sim_iccid": "89883070000123456789",17"status": "received",18"direction": "from_sim",19"device_ip": "100.64.0.123",20"device_port": 100,21"payload_type": "text",22"payload": "checkin: firmware update",23"date_created": "2015-07-30T20:00:00Z",24"date_updated": "2015-07-30T20:00:00Z",25"url": "https://supersim.twilio.com/v1/IpCommands/HGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"26}27]28}