IPCommand Resource
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/IpCommandsYou 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 to SIM (Mobile Terminated)
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:
- 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.
- 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.
- 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)
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 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
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
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 our support team. For more information on Twilio’s data retention and deletion policy, please see this support document.
IpCommand properties
| Resource Properties in REST API format | |
|---|---|
sid
|
The unique string that we created to identify the IP Command resource. |
account_sid
|
The SID of the Account that created the IP Command resource. |
sim_sid
|
The SID of the Super SIM that this IP Command was sent to or from. |
sim_iccid
|
The ICCID of the Super SIM that this IP Command was sent to or from. |
status
|
The delivery status of the IP Command. This is one of the following: “queued”, “sent”, “failed” or “received”. |
direction
|
Either |
device_ip
|
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_port
|
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. |
payload_type
|
Either “text” or “binary”. For an IP Command sent to a Super SIM, |
payload
|
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_created
|
The date and time in GMT when the resource was created specified in ISO 8601 format. |
date_updated
|
The date and time in GMT when the resource was last updated specified in ISO 8601 format. |
url
|
The absolute URL of the IP Command resource. |
Status values
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. |
IpCommand resource status callbacks
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 |
ErrorMessage |
Description of the error. Unless the status is failed, ErrorMessage will not be present. |
Error scenarios
Synchronous errors
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
activenorready. - 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
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
https://supersim.twilio.com/v1/IpCommands
Parameters
| Parameters in REST API format | |
|---|---|
sim
Required
|
The |
payload
Required
|
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. |
device_port
Required
|
The device port to which the IP Command will be sent. |
payload_type
Optional
|
Indicates how the payload is encoded. Either |
callback_url
Optional
|
The URL we should call using the |
callback_method
Optional
|
The HTTP method we should use to call |
Example 1
Fetch an IpCommand resource
https://supersim.twilio.com/v1/IpCommands/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
sid
Path
|
The SID of the IP Command resource to fetch. |
Example 1
Read multiple IpCommand resources
https://supersim.twilio.com/v1/IpCommands
Parameters
| Parameters in REST API format | |
|---|---|
sim
Optional
|
The SID or unique name of the Sim resource that IP Command was sent to or from. |
sim_iccid
Optional
|
The ICCID of the Sim resource that IP Command was sent to or from. |
status
Optional
|
The status of the IP Command. Can be: |
direction
Optional
|
The direction of the IP Command. Can be |
Example 1
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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
