IPCommand Resource

Transfer IP/UDP messages between your cloud and your devices

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 KORE 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.api.korewireless.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 can be used as 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 KORE 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 created IP Command resource's status will initially be queued. The IP Command will be sent to the device asynchronously on an existing data connection. If the device is attached, we will attempt to send the UDP message to your device and the IP Command resource's status will be updated to sent. 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.

Learn more about:

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 KORE 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 your device 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 created IP Command resource's status will always be received.

Learn more about the contents of the IP Command callbacks below.

API Authorization

Before you can make requests to this resource, you must have a valid bearer token. Review our API authorization guide to learn how to generate a token. Here's a curl example on how to define your access token in a header:

curl -X GET \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
'https://supersim.api.korewireless.com/v1/Sims'

The examples below do not show the required Authorization header due to a bug. We're working on fixing that. In the meantime, be sure to include that in all of your requests.

Send an IP Command

Send an IP Command to a Super SIM.

POSThttps://supersim.api.korewireless.com/v1/IpCommands

Authorization

Body

Sim*string

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

Payload*string

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.

DevicePort*integer

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

PayloadTypeip_command_enum_payload_type (enum)

textbinary

CallbackUrlstring (uri)

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

CallbackMethodenum

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

GETPOST

Response

Created

Headers

Body

sidnullable string

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

Pattern: ^HG[0-9a-fA-F]{32}$

account_sidnullable string

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

Pattern: ^AC[0-9a-fA-F]{32}$

sim_sidnullable string

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

Pattern: ^HS[0-9a-fA-F]{32}$

sim_iccidnullable string

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

statusip_command_enum_status (enum)

queuedsentreceivedfailed

directionip_command_enum_direction (enum)

to_simfrom_sim

device_ipnullable string

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

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_typeip_command_enum_payload_type (enum)

textbinary

payloadnullable string

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_creatednullable string (date-time)

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

date_updatednullable string (date-time)

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

urlnullable string (uri)

The absolute URL of the IP Command resource.

Request

const response = await fetch('https://supersim.api.korewireless.com/v1/IpCommands', {
    method: 'POST',
    headers: {
      "Content-Type": "application/x-www-form-urlencoded"
    },
    body: JSON.stringify({
      "Sim": "sim",
      "Payload": "checkin: firmware update",
      "DevicePort": 100,
      "PayloadType": "text",
      "CallbackUrl": "http://www.example.com",
      "CallbackMethod": "GET"
    }),
});
const data = await response.json();

Response

{
  "sid": "text",
  "account_sid": "text",
  "sim_sid": "text",
  "sim_iccid": "text",
  "status": "queued",
  "direction": "to_sim",
  "device_ip": "text",
  "device_port": 0,
  "payload_type": "text",
  "payload": "text",
  "date_created": "2024-12-21T15:02:18.701Z",
  "date_updated": "2024-12-21T15:02:18.701Z",
  "url": "https://example.com"
}

Fetch an IP Command

Fetch IP Command instance from your account.

GEThttps://supersim.api.korewireless.com/v1/IpCommands/{Sid}

Authorization

Path parameters

Sid*string

The SID of the IP Command resource to fetch.

Pattern: ^HG[0-9a-fA-F]{32}$

Response

Headers

Body

sidnullable string

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

Pattern: ^HG[0-9a-fA-F]{32}$

account_sidnullable string

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

Pattern: ^AC[0-9a-fA-F]{32}$

sim_sidnullable string

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

Pattern: ^HS[0-9a-fA-F]{32}$

sim_iccidnullable string

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

statusip_command_enum_status (enum)

queuedsentreceivedfailed

directionip_command_enum_direction (enum)

to_simfrom_sim

device_ipnullable string

device_portnullable integer

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_typeip_command_enum_payload_type (enum)

textbinary

payloadnullable string

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.

date_creatednullable string (date-time)

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

date_updatednullable string (date-time)

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

urlnullable string (uri)

The absolute URL of the IP Command resource.

Request

const response = await fetch('https://supersim.api.korewireless.com/v1/IpCommands/{Sid}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "sid": "text",
  "account_sid": "text",
  "sim_sid": "text",
  "sim_iccid": "text",
  "status": "queued",
  "direction": "to_sim",
  "device_ip": "text",
  "device_port": 0,
  "payload_type": "text",
  "payload": "text",
  "date_created": "2024-12-21T15:02:18.701Z",
  "date_updated": "2024-12-21T15:02:18.701Z",
  "url": "https://example.com"
}

List Your IP Commands

Retrieve a list of IP Commands from your account.

GEThttps://supersim.api.korewireless.com/v1/IpCommands

Authorization

Query parameters

Response

Headers

Body

ip_commandsarray of supersim.v1.ip_command (object)

metaobject

Request

const response = await fetch('https://supersim.api.korewireless.com/v1/IpCommands', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "ip_commands": [
    {
      "sid": "text",
      "account_sid": "text",
      "sim_sid": "text",
      "sim_iccid": "text",
      "status": "queued",
      "direction": "to_sim",
      "device_ip": "text",
      "device_port": 0,
      "payload_type": "text",
      "payload": "text",
      "date_created": "2024-12-21T15:02:18.701Z",
      "date_updated": "2024-12-21T15:02:18.701Z",
      "url": "https://example.com"
    }
  ],
  "meta": {
    "first_page_url": "https://example.com",
    "key": "text",
    "next_page_url": "https://example.com",
    "page": 0,
    "page_size": 0,
    "previous_page_url": "https://example.com",
    "url": "https://example.com"
  }
}

Status Values

The table below describes the available status values of an IP Command resource. 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.

An IP Command resource will have one of the following statuses:

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.

IP Command Resource Callbacks

You can receive callbacks when:

An IP Command resource representing an IP Command to be sent to your device advances through its statuses. The callback is sent to the URL included in your API request.
An IP Command is received from your device and a corresponding IP Command resource is created. The callback is sent to the ip_commands_callback_url defined on the Fleet to which the SIM is assigned.

You can see an example below of a request to send an IP Command to a device, the response to that request, and the callback sent after the IP Command was sent.

curl -L -X POST "https://supersim.api.korewireless.com/v1/IpCommands" \
--header "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
--data-urlencode "Payload={\"enable\":\"True\", \"reset\":\"False\",\"when\":\"Immediate\"}" \
--data-urlencode "Sim=HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
--data-urlencode "DevicePort=3030" \
--data-urlencode "CallbackUrl=<YOUR_CALLBACK_URL>" \
--data-urlencode "CallbackMethod=GET"

{
    "account_sid":"ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "sid":"HCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "sim_sid":"HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "sim_iccid":"89nnnnnnnnnnnnnnnnnn",
    "date_created":"2024-10-24T20:39:13.474616Z",
    "date_updated":"2024-10-24T20:39:13.474616Z",
    "device_port":3030,
    "payload":"{\"command\":\"wake up\",\"timestamp\":\"2024-03-08-14-02-49}\"",
    "payload_type":"text",
    "status":"queued",
    "device_ip":null,
    "error_code":null,
    "direction":"to_sim",   
    "url":"https://supersim.api.korewireless.com/v1/IpCommands/HGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Status sent
ApiVersion v1
SimUniqueName Parking-Meter-Lot-Area-001
Payload {"enable":"True", "reset":"False","when":"Immediate"}
SimSid HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
CommandSid HGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Direction to_sim
AccountSid ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
SimIccid 89nnnnnnnnnnnnnnnnnn
PayloadType text

The request sent to the callback URL contains the following properties:

AccountSid

The SID of the Account that the SMS Command resource belongs to. For example: ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

CommandSid

The unique string that we created to identify the SMS Command resource. For example: HGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

SimSid

The receiving Super SIM's SID. For example: HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

SimUniqueName

The receiving Super SIM's UniqueName. For example: Parking-Meter-Lot-Area-001

Payload

The body of the SMS Command message. This value can be up to 160 characters of text. Binary mode is not supported. For example: {"enable":"True", "reset":"False","When":"Immediate"}

PayloadType

text mode by default. Binary mode is not supported.

Direction

Indicates whether the Command is MT or MO. It has two possible values: to_sim or from_sim.

Status

The delivery status of the SMS Command.

ErrorCode

The error code (if any) associated with a failed SMS Command. Unless the status is failed, ErrorCode will not be present.

ErrorMessage

A description of the error (if any) associated with a failed SMS Command. 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.

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.

PreviousSMSCommand Resource NextProgrammable Wireless

Last updated 1 month ago