IPCommand Resource

Transfer IP/UDP messages between your cloud and your devices

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 -L "https://supersim.api.korewireless.com/v1/Sims" -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

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

post

Send an IP Command to a Super SIM.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Body

SimstringRequired

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

PayloadstringRequired

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

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

PayloadTypestring · enum · nullableOptional

Indicates how the payload is encoded. 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:

CallbackUrlstring · uriOptional

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

CallbackMethodstring · enumOptional

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

Possible values:

Responses

201

Created

application/json

post

/v1/IpCommands

curl -X POST "https://supersim.api.korewireless.com/v1/IpCommands" -H "Content-Type: application/x-www-form-urlencoded" -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" --data-urlencode "Sim=<Sid>" --data-urlencode "Payload=<IP_COMMAND_PAYLOAD>" --data-urlencode "DevicePort=<DEVICE_PORT>" --data-urlencode "PayloadType=<text|binary>"  --data-urlencode "CallbackUrl=<YOUR_CALLBACK_URL>" --data-urlencode "CallbackMethod=<GET_OR_POST>"

201

Created

{
  "sid": "HGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "sim_iccid": "89883070000123456789",
  "status": "queued",
  "direction": "to_sim",
  "device_ip": "100.64.0.123",
  "device_port": 100,
  "payload_type": "text",
  "payload": "checkin: firmware update",
  "date_created": "2015-07-30T20:00:00Z",
  "date_updated": "2015-07-30T20:00:00Z",
  "url": "https://supersim.api.korewireless.com/v1/IpCommands/HGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Fetch an IP Command

get

Fetch IP Command instance from your account.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

Sidstring · min: 34 · max: 34Required

The SID of the IP Command resource to fetch.

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

Responses

200

application/json

get

/v1/IpCommands/{Sid}

curl -L "https://supersim.api.korewireless.com/v1/IpCommands/<IP_COMMAND_SID>" -H "Content-Type: application/x-www-form-urlencoded" -H "Authorization: Bearer <YOUR_AUTH_TOKEN>"

200

{
  "sid": "HGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "sim_iccid": "89883070000123456789",
  "status": "queued",
  "direction": "to_sim",
  "device_ip": "100.64.0.123",
  "device_port": 100,
  "payload_type": "text",
  "payload": "checkin: firmware update",
  "date_created": "2015-07-30T20:00:00Z",
  "date_updated": "2015-07-30T20:00:00Z",
  "url": "https://supersim.api.korewireless.com/v1/IpCommands/HGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

List Your IP Commands

get

Retrieve a list of IP Commands from your account.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Query parameters

SimstringOptional

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

Example: {"value":"HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}

SimIccidstringOptional

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

Statusstring · enum · nullableOptional

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

Example: {"value":"received"}Possible values:

Directionstring · enum · nullableOptional

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

Possible values:

PageSizeinteger · min: 1 · max: 100Optional

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

PageintegerOptional

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

PageTokenstringOptional

The page token. This is provided by the API.

Responses

200

application/json

get

/v1/IpCommands

curl -L "https://supersim.api.korewireless.com/v1/IpCommands?Sim=<Sid>&Page=1&PageSize=10" -H "Content-Type: application/x-www-form-urlencoded" -H "Authorization: Bearer <YOUR_AUTH_TOKEN>"

200

{
  "ip_commands": [],
  "meta": {
    "first_page_url": "https://supersim.api.korewireless.com/v1/IpCommands?Status=received&Sim=HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",
    "key": "ip_commands",
    "next_page_url": null,
    "page": 0,
    "page_size": 50,
    "previous_page_url": null,
    "url": "https://supersim.api.korewireless.com/v1/IpCommands?Status=received&Sim=HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0"
  }
}

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 10 months ago

Was this helpful?

hashtagIP Commands to SIM (Mobile Terminated)

hashtagIP Commands from SIM (Mobile Originated)

hashtagAPI Authorization

hashtagSend an IP Command

hashtagFetch an IP Command

hashtagList Your IP Commands

hashtagStatus Values

hashtagIP Command Resource Callbacks

hashtagError Scenarios

hashtagSynchronous Errors

hashtagAsynchronous Errors

hashtagRetention Period

IP Commands to SIM (Mobile Terminated)

IP Commands from SIM (Mobile Originated)

API Authorization

Send an IP Command

Fetch an IP Command

List Your IP Commands

Status Values

IP Command Resource Callbacks

Error Scenarios

Synchronous Errors

Asynchronous Errors

Retention Period