Skip to contentSkip to navigationSkip to topbar
Twilio Docs
On this page

IPCommand Resource

(warning)

Public Beta

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(link takes you to an external page).

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.

(information)

Info

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.

(information)

Info

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 to SIM (Mobile Terminated)

ip-commands-to-sim-mobile-terminated page anchor

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.

(information)

Info

If the device is sleeping (3GPP IDLE mode(link takes you to an external page)), IP Commands can still be delivered to the device. There are three scenarios here:

  1. Regular LTE devices — When the IP message reaches the visited network to which your device is attached to, the visited network will page your device. When your device responds to the page, it will receive the IP Command.
  2. Cat-M1 devices without eDRX — IP Commands sent to Cat-M1 devices which do not have eDRX mode enabled are treated like regular LTE devices. Your device will get paged and the IP message is delivered when your device responds to the page.
  3. Cat-M1 devices that use eDRX sleep mode — HLCOM (High Latency Communication) is a network feature that allows a Cat-M1 device sleeping in eDRX mode to avoid being paged for IP messages. Instead the IP message is buffered in the visited network and delivered when the device comes out of the sleep cycle. HLCOM is not available on all cellular networks. If HLCOM is not enabled and the device is sleeping in eDRX mode, then the IP message is dropped in the visited network and will not be delivered to your device.

IP Commands from SIM (Mobile Originated)

ip-commands-from-sim-mobile-originated page anchor

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.

Asynchronous updates

asynchronous-updates page anchor

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.

Retention period

retention-period page anchor

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.

(information)

Info

Customers may request that IP Command data be deleted. If you wish to do so, please contact Twilio Support through the Console(link takes you to an external page) or Help Center(link takes you to an external page). For more information on Twilio's data retention and deletion policy, please see this support document(link takes you to an external page).

IpCommand Properties

ipcommand-properties page anchor
Property nameTypeRequiredDescriptionChild properties
sidSID<HG>Optional
Not PII

The unique string that we created to identify the IP Command resource.

Pattern: ^HG[0-9a-fA-F]{32}$Min length: 34Max length: 34
account_sidSID<AC>Optional
Not PII

The SID of the Account that created the IP Command resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
sim_sidSID<HS>Optional
Not PII

The SID of the Super SIM that this IP Command was sent to or from.

Pattern: ^HS[0-9a-fA-F]{32}$Min length: 34Max length: 34
sim_iccidstringOptional
Not PII

The ICCID(link takes you to an external page) of the Super SIM that this IP Command was sent to or from.

statusenum<string>Optional
Not PII

The delivery status of the IP Command. This is one of the following: “queued”, “sent”, “failed” or “received”.

Possible values:
queuedsentreceivedfailed
directionenum<string>Optional
Not PII

Either to_sim or from_sim. Indicates whether the IP Command resource was sent from or to the Super SIM.

Possible values:
to_simfrom_sim
device_ipstringOptional
Not PII

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.

device_portintegerOptional
Not PII

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.

Default: 0
payload_typeenum<string>Optional
Not PII

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”.

Possible values:
textbinary
payloadstringOptional
PII MTL: 30 days

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.

date_createdstring<date-time>Optional
Not PII

The date and time in GMT when the resource was created specified in ISO 8601(link takes you to an external page) format.

date_updatedstring<date-time>Optional
Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601(link takes you to an external page) format.

urlstring<uri>Optional
Not PII

The absolute URL of the IP Command resource.

Status values

status-values page anchor

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.

queuedThe IP Command was accepted and is queued in our service waiting to be sent.
sentThe IP Command was sent to the SIM in the form of an IP message.
receivedThe IP Command was received from the SIM.
failedThe IP Command could not be sent.

IpCommand resource status callbacks

ipcommand-resource-status-callbacks page anchor

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:

AccountSidThe SID of the Account that created the Command resource.
CommandSidThe unique string that was created to identify the Command resource.
SimSidThe SID of the SIM that this Command was sent to or from.
SimUniqueNameThe Unique Name of the Super SIM that this Command was sent to or from.
PayloadTypeThe 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.
PayloadThe 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.
DirectionIndicates whether it is an mobile terminated or mobile originated Command. It has two possible values: to_sim or from_sim.
StatusThe delivery status of the Command. Applicable statuses for IP Commands are queued, sent, and failed. See Status values for more information.
ErrorCodeThe error code, if any, associated with your Command. Unless the status is failed, ErrorCode will not be present.
ErrorMessageDescription of the error. Unless the status is failed, ErrorMessage will not be present.

Error scenarios

error-scenarios page anchor

Synchronous errors

synchronous-errors page anchor

The following scenarios will return a synchronous 4xx error:

  • Unknown SIM — The SIM SID or Unique Name given to the API does not belong to the requesting account.
  • Invalid SIM State — The SIM to which the IP Command would be sent is neither active nor ready.
  • Payload Too Big — The decoded payload is too large to send in a single UDP request. The maximum size is 1300 bytes. This will produce an HTTP error 400.

Asynchronous errors

asynchronous-errors page anchor

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:

  • Device Not Attached — The device was not attached to a cellular network when the IP Command was dequeued. The Command was not sent to the device.

Create an IpCommand resource

create-an-ipcommand-resource page anchor
POST https://supersim.twilio.com/v1/IpCommands

Request body parameters

request-body-parameters page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
Simstringrequired
Not PII

The sid or unique_name of the Super SIM to send the IP Command to.

Payloadstringrequired
PII MTL: 30 days

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.

DevicePortintegerrequired
Not PII

The device port to which the IP Command will be sent.

PayloadTypeenum<string>Optional
Not PII

Indicates how the payload is encoded. Either text or binary. Defaults to text.

Possible values:
textbinary
CallbackUrlstring<uri>Optional
Not PII

The URL we should call using the callback_method after we have sent the IP Command.

CallbackMethodenum<http-method>Optional
Not PII

The HTTP method we should use to call callback_url. Can be GET or POST, and the default is POST.

Possible values:
GETPOST
Create Ip CommandLink to code sample: Create Ip Command
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createIpCommand() {

11
  const ipCommand = await client.supersim.v1.ipCommands.create({

12
    devicePort: 42,

13
    payload: "Payload",

14
    sim: "Sim",

15
  });

16


17
  console.log(ipCommand.sid);

18
}

19


20
createIpCommand();

Output

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
}

Fetch an IpCommand resource

fetch-an-ipcommand-resource page anchor
GET https://supersim.twilio.com/v1/IpCommands/{Sid}

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
SidSID<HG>required
Not PII

The SID of the IP Command resource to fetch.

Pattern: ^HG[0-9a-fA-F]{32}$Min length: 34Max length: 34
Fetch Ip CommandLink to code sample: Fetch Ip Command
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function fetchIpCommand() {

11
  const ipCommand = await client.supersim.v1

12
    .ipCommands("HGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .fetch();

14


15
  console.log(ipCommand.sid);

16
}

17


18
fetchIpCommand();

Output

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
}

Read multiple IpCommand resources

read-multiple-ipcommand-resources page anchor
GET https://supersim.twilio.com/v1/IpCommands

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
SimstringOptional
Not PII

The SID or unique name of the Sim resource that IP Command was sent to or from.

SimIccidstringOptional
Not PII

The ICCID of the Sim resource that IP Command was sent to or from.

Statusenum<string>Optional
Not PII

The status of the IP Command. Can be: queued, sent, received or failed. See the IP Command Status Values for a description of each.

Possible values:
queuedsentreceivedfailed
Directionenum<string>Optional
Not PII

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.

Possible values:
to_simfrom_sim
PageSizeintegerOptional
Not PII

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000
PageintegerOptional
Not PII

The page index. This value is simply for client state.

Minimum: 0
PageTokenstringOptional
Not PII

The page token. This is provided by the API.

Read Ip CommandLink to code sample: Read Ip Command
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function listIpCommand() {

11
  const ipCommands = await client.supersim.v1.ipCommands.list({ limit: 20 });

12


13
  ipCommands.forEach((i) => console.log(i.sid));

14
}

15


16
listIpCommand();

Output

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
}

Need some help?

Terms of service
Privacy Policy

Copyright © 2024 Twilio Inc.