# Command Resource

***

The **Command** resource enables you to exchange machine-to-machine messages with SMS-capable devices. For example, you could use a **Command** resource to instruct a device to take a sensor reading.

While SMS is used as the transport, the SIM does not require an addressable phone number to receive a Command. This is the major distinction from KORE's Messages resource, which can be used for conversational messaging.

Any SMS message sent *from* a SIM to a pre-determined phone number — see [Receive a Command from a SIM](#receive-a-command-from-a-sim) — is interpreted as a Command and sent to the Command callback URL of the [**Sim** resource](https://docs.korewireless.com/en-us/api/products/programmable-wireless/wireless-sim-resource).

Commands can be sent and received using the SMS text mode or binary (PDU) mode. Text-mode Commands have a maximum length of 160 single-byte characters. Binary-mode Commands have a maximum length of 140 bytes.

To receive and process a Command sent to your device, you will interface with the modem directly, probably using AT commands. You should consult with the module manufacturer's documentation for information about receiving SMS messages.

***

## Asynchronous resources <a href="#asynchronous-resources" id="asynchronous-resources"></a>

The Command resource performs [asynchronous operations](https://docs.korewireless.com/en-us/api/products/programmable-wireless/). To receive an asynchronous notification when a Command resource has finished updating, provide a callback URL, and optionally a callback method, `GET` or `POST`, when you create the Command.

***

## Retention period <a href="#retention-period" id="retention-period"></a>

Commands are retained for 30 days from the time they are created. Commands older than 30 days will no longer be readable from this resource.

***

## Command Properties <a href="#command-properties" id="command-properties"></a>

**sid** SID\<DC>                                                                                                                                        &#x20;

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

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

Min length:`34`

Max length:`34`

***

**account\_sid** SID\<AC>                                                                                                                      &#x20;

The SID of the Account that created the Command resource.

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

Min length:`34`

Max length:`34`

***

**sim\_sid** SID\<DE>                                                                                                                                   &#x20;

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

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

Min length:`34`

Max length:`34`

***

**command** string                                                                                                                              PII MTL: 30 days

The message being sent to or from the SIM. For text mode messages, this can be up to 160 characters. For binary mode messages, this is a series of up to 140 bytes of data encoded using base64.

***

**command\_mode**  enum\<string>                                                                                                 &#x20;

The mode used to send the SMS message. Can be: `text` or `binary`. The default SMS mode is `text`.

Possible values:

`text`

`binary`

***

**transport**  enum\<string>                                                                                                                 &#x20;

The type of transport used. Can be: `sms` or `ip`.

Possible values:

`sms`

`ip`

***

**delivery\_receipt\_requested** boolean                                                                                               &#x20;

Whether to request a delivery receipt.

***

**status** enum\<string>                                                                                                                          &#x20;

The status of the Command. Can be: `queued`, `sent`, `delivered`, `received`, or `failed`. See [Status Values](#status-values) for a description of each state.

Possible values:

`queued`

`sent`

`delivered`

`received`

`failed`

***

**direction** enum\<string>                                                                                                                    &#x20;

The direction of the 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:

`from_sim`

`to_sim`

***

**date\_created**  string\<date-time>                                                                                                       &#x20;

The date and time in GMT when the resource was created specified in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.

***

**date\_updated**  string\<date-time>                                                                                                   &#x20;

The date and time in GMT when the resource was last updated specified in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.

***

**url**  string\<uri>                                                                                                                                       &#x20;

The absolute URL of the resource.

## Status values <a href="#status-values" id="status-values"></a>

| Status      | Description                                                               |
| ----------- | ------------------------------------------------------------------------- |
| `queued`    | The Command is queued in our network waiting to be sent to the SIM.       |
| `sent`      | The Command has been sent to the SIM.                                     |
| `delivered` | The Command has been delivered to the SIM. For `to_sim` Commands only.    |
| `received`  | The Command has been received from the SIM. For `from_sim` Commands only. |
| `failed`    | The Command has failed to be transmitted.                                 |

***

## Create a Command resource <a href="#create-a-command-resource" id="create-a-command-resource"></a>

Creating a Command resource sends the `command` to the SIM.

### Callback values <a href="#callback-values" id="callback-values"></a>

Outgoing Command delivery is [asynchronous](#asynchronous-resources), so we recommend that you pass a callback URL when you create the new Command.

When you provide a callback URL, we call it when the attempt to send the Command completes.

If the `CallbackMethod` parameter was set to `POST,` or not provided, the callback parameters are delivered as HTML form parameters. If the `CallbackMethod` parameter was set to `GET`, the callback parameters are delivered as a query string.

## Send a Command to a Sim

{% openapi src="/files/J4rPRhkD7uutXjbzb7DT" path="/v1/Commands" method="post" %}
[openapi3\_0 (alf).yaml](https://3487028960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJknMM6SZJYk9EbbitKp5%2Fuploads%2F4alsAWeuMtriesOfOixr%2Fopenapi3_0%20\(alf\).yaml?alt=media\&token=8a6481d4-a087-4460-b7cd-9e4a4d0e6341)
{% endopenapi %}

***

## Fetch a Command resource <a href="#fetch-a-command-resource" id="fetch-a-command-resource"></a>

{% openapi src="/files/J4rPRhkD7uutXjbzb7DT" path="/v1/Commands/{Sid}" method="get" %}
[openapi3\_0 (alf).yaml](https://3487028960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJknMM6SZJYk9EbbitKp5%2Fuploads%2F4alsAWeuMtriesOfOixr%2Fopenapi3_0%20\(alf\).yaml?alt=media\&token=8a6481d4-a087-4460-b7cd-9e4a4d0e6341)
{% endopenapi %}

***

## Read multiple Command resources <a href="#read-multiple-command-resources" id="read-multiple-command-resources"></a>

{% hint style="warning" %}
The maximum `PageSize` you can request when reading Commands is 100.
{% endhint %}

{% openapi src="/files/J4rPRhkD7uutXjbzb7DT" path="/v1/Commands" method="get" %}
[openapi3\_0 (alf).yaml](https://3487028960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJknMM6SZJYk9EbbitKp5%2Fuploads%2F4alsAWeuMtriesOfOixr%2Fopenapi3_0%20\(alf\).yaml?alt=media\&token=8a6481d4-a087-4460-b7cd-9e4a4d0e6341)
{% endopenapi %}

***

## Delete a Command resource <a href="#delete-a-command-resource" id="delete-a-command-resource"></a>

{% openapi src="/files/J4rPRhkD7uutXjbzb7DT" path="/v1/Commands/{Sid}" method="delete" %}
[openapi3\_0 (alf).yaml](https://3487028960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJknMM6SZJYk9EbbitKp5%2Fuploads%2F4alsAWeuMtriesOfOixr%2Fopenapi3_0%20\(alf\).yaml?alt=media\&token=8a6481d4-a087-4460-b7cd-9e4a4d0e6341)
{% endopenapi %}

***

## Receive a Command from a SIM <a href="#receive-a-command-from-a-sim" id="receive-a-command-from-a-sim"></a>

To receive a Command from a SIM — called a "mobile-originated" Command — you should create or update an existing [Sim](https://docs.korewireless.com/en-us/api/products/programmable-wireless/wireless-sim-resource) instance and provide a `CommandsCallbackUrl` property. Optionally, you may also include a `CommandsCallbackMethod` property.

When a SIM sends an SMS message to the reserved phone number `2936`, a Command resource will be created, and your Commands Callback URL will be invoked. The callback request will include the following parameters.

| Parameter       | Description                                                                                                                                                                                     |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CommandSid`    | The SID of this Command.                                                                                                                                                                        |
| `SimSid`        | The SIM this Command was sent by.                                                                                                                                                               |
| `SimUniqueName` | The sending SIM's friendly name, if it has one.                                                                                                                                                 |
| `Command`       | The body of the Command message. In `text` mode, this value can be up to 160 characters of text. In `binary` mode, this value is a Base64 encoded byte string with a maximum size of 140 bytes. |
| `Status`        | Will always be the string `received`.                                                                                                                                                           |
| `ApiVersion`    | The version of the API that your initial request was made to.                                                                                                                                   |
| `AccountSid`    | The SID of the Account that this Command belongs to.                                                                                                                                            |
| `CommandMode`   | A string representing which mode the SMS was received as. May be `text` or `binary`.                                                                                                            |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.korewireless.com/api/products/programmable-wireless/command-resource.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.