Menu

Expand
Rate this page:

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/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 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:

  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)

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
sid<HG> Not PII

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

account_sid
sid<AC> Not PII

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

sim_sid
sid<HS> Not PII

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

sim_iccid
string Not PII

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

status
enum:status Not PII

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

direction
enum:direction Not PII

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

device_ip
string 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_port
integer 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.

payload_type
enum:payload_type 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”.

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
date_time<iso8601> Not PII

The date and time in GMT when the resource was created specified in ISO 8601 format.

date_updated
date_time<iso8601> Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601 format.

url
url Not PII

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 failed, ErrorCode will not be present.

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

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

post
https://supersim.twilio.com/v1/IpCommands
Parameters
Parameters in REST API format
sim
Required
post string Not PII

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

payload
Required
post string 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.

device_port
Required
post integer Not PII

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

payload_type
Optional
post ienum:payload_type Not PII

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

callback_url
Optional
post url Not PII

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

callback_method
Optional
post http_method Not PII

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

Example 1
Loading Code Sample...
        
        
        

        Create Ip Command

        Fetch an IpCommand resource

        get
        https://supersim.twilio.com/v1/IpCommands/{Sid}
        Parameters
        Parameters in REST API format
        sid
        Path
        get sid<HG> Not PII

        The SID of the IP Command resource to fetch.

        Example 1
        Loading Code Sample...
              
              
              

              Fetch Ip Command

              Read multiple IpCommand resources

              get
              https://supersim.twilio.com/v1/IpCommands
              Parameters
              Parameters in REST API format
              sim
              Optional
              get sid_like<HS> Not PII

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

              sim_iccid
              Optional
              get string Not PII

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

              status
              Optional
              get ienum:status 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.

              direction
              Optional
              get ienum:direction 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.

              Example 1
              Loading Code Sample...
                    
                    
                    

                    Read Ip Command

                    Rate this page:

                    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.

                    Loading Code Sample...
                          
                          
                          

                          Thank you for your feedback!

                          Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                          Sending your feedback...
                          🎉 Thank you for your feedback!
                          Something went wrong. Please try again.

                          Thanks for your feedback!

                          thanks-feedback-gif