# 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="<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>" 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="<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>" 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="<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>" 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="<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>" 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`.                                                                                                            |