# Get Started with Programmable Wireless Machine-to-Machine SMS Commands

You've got a Programmable Wireless SIM in your device and you want to start sending machine-to-machine (M2M) SMS messages. You do so using the Programmable Wireless Commands API. This short guide will show you how.

***

### How are Commands different from Programmable SMS? <a href="#how-are-commands-different-from-programmable-sms" id="how-are-commands-different-from-programmable-sms"></a>

Programmable SMS is used to exchange text messages between people. Commands use SMS as the means to deliver messages between machines.

You use [Command resources](https://docs.korewireless.com/en-us/api/products/programmable-wireless/command-resource) to send a command message to a Programmable Wireless SIM, not to a person's phone number. Commands also provide some features, such as binary message encoding, that are only useful for M2M workflows.

{% hint style="info" %}
You can get all the details you need to use [Command resources](https://docs.korewireless.com/en-us/api/products/programmable-wireless/command-resource) in [the Programmable Wireless API documentation](https://docs.korewireless.com/en-us/api/products/programmable-wireless).
{% endhint %}

{% hint style="warning" %}
This guide is intended for the Programmable Wireless SIM. It is not intended for the Narrowband SIM, which does not support messaging, only data services.
{% endhint %}

### Send a Command from your device <a href="#send-a-command-from-your-device" id="send-a-command-from-your-device"></a>

Let's say you want to send a Command from your device to KORE's servers to either:

* Test Commands themselves.
* Hit the [Commands callback webhook](https://docs.korewireless.com/en-us/api/products/programmable-wireless/command-resource#callback-values) to check that your server is notified when Commands are transmitted.

How you send a Command is largely dependent on the type of device you use to send it. Generally, you need to do the following:

1. Insert a Programmable Wireless SIM in the device.
2. Make sure the SIM has been registered to your account and is in the `Ready` or `Active` [state](https://docs.korewireless.com/programmable-wireless/help-and-support/about-sim-states) .
3. Send an SMS to the short code 2936.

#### What is this 2936 number? <a href="#what-is-this-2936-number" id="what-is-this-2936-number"></a>

2936 is a special reserved short code used solely to exchange Commands with your Programmable Wireless SIMs. KORE uses a given SIM's unique identifier to route Commands sent to 2936 through your account.

#### Verify that the target machine received the Command <a href="#verify-that-the-target-machine-received-the-command" id="verify-that-the-target-machine-received-the-command"></a>

* Navigate to the [**SIMs**](https://programmable-wireless.korewireless.com/wireless/sims) section of the Console.
* At the list of SIMs on your account, click on the SIM that is in your device .
* Click on the **Commands** tab at the top of the SIM details.
* You should see your first Command sent from a machine to a machine:

  <figure><img src="https://3566848590-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9p1Cs774U7DhQF5Pc3aj%2Fuploads%2F85PPP3fD5v8tMbFRbAgT%2Fimage.png?alt=media&#x26;token=5f3b8c5c-033b-4068-8301-8a05be27f263" alt=""><figcaption></figcaption></figure>

#### Relay messages to your cloud <a href="#relay-messages-to-your-cloud" id="relay-messages-to-your-cloud"></a>

The Console page showing your SIM's configuration — select **Configure** if you're still on the **Commands** tab — has a section called **Commands** with a **Commands Callback URL** field. This is where you enter the address of an endpoint in your cloud that will receive Commands send from the device.

If you don't have such an endpoint in place yet, you can use a service like [Beeceptor](https://beeceptor.com/) to try it out. Beeceptor offers free mock servers — virtual endpoints that can receive webhook calls. Let's set one up to receive messages from the device.

1. In a fresh web browser tab, go to [Beeceptor](https://beeceptor.com/):<br>

   <figure><img src="https://3566848590-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9p1Cs774U7DhQF5Pc3aj%2Fuploads%2FDuP4zet6X17dqQkhRpfS%2Fimage.png?alt=media&#x26;token=ac35ac3b-b125-43f7-90b7-90e51f5ef26a" alt=""><figcaption></figcaption></figure>
2. Enter an endpoint name in the large text field and click **Create Endpoint** .
3. On the screen that appears next, click on the upper of the two **clipboard icons** to copy the endpoint URL:<br>

   <figure><img src="https://3566848590-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9p1Cs774U7DhQF5Pc3aj%2Fuploads%2Fru3eJw5TL7Ml0GVTRz2Y%2Fimage.png?alt=media&#x26;token=d0675c35-aa5d-408b-99d8-8374fe544c72" alt=""><figcaption></figcaption></figure>
4. Keep the tab open.
5. Go back to the web browser tab showing the KORE Console and paste the URL into the **Commands Callback URL** field.
6. Click **Save** .
7. Now send a second Command from the device. This time it will be relayed to your Beeceptor endpoint and you can read it in the Beeceptor tab in your browser. You should see — or will shortly see — the endpoint has received a `POST` request:<br>

   <figure><img src="https://3566848590-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9p1Cs774U7DhQF5Pc3aj%2Fuploads%2FcHFtpiZ3nJJHae9LCWbz%2Fimage.png?alt=media&#x26;token=33efc5c2-e949-410f-846d-3943134ca684" alt=""><figcaption></figcaption></figure>
8. Click on it to see the request body, then on the JSON icon, **{:}**, to view the data more clearly:<br>

   <figure><img src="https://3566848590-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9p1Cs774U7DhQF5Pc3aj%2Fuploads%2FPNv8vtAJonSDbybpWBM8%2Fimage.png?alt=media&#x26;token=8285234c-51eb-4a00-94b4-a482072c6839" alt=""><figcaption></figcaption></figure>

This is essentially how your IoT device will send Commands to your cloud. Here's the flow in this case:

* IoT device sends the command to KORE at 2936
* KORE `POST` s a request containing the Command to your cloud at the specified endpoint.
* Your cloud-side app extracts and processes the command.

***

### Send a Command to your device <a href="#send-a-command-to-your-device" id="send-a-command-to-your-device"></a>

You can send Commands from any Internet-connected device using the Programmable Wireless API. Typically the Command would come from your cloud.

You can do it right now on your computer. You'll need to use the command line tool *curl*, which you may need to install. If you are running Linux or macOS, *curl* is probably installed already: run `which curl` to check. For Windows, you will need to install *curl* — you can find the software and instructions from the source [here](https://curl.haxx.se/windows/).

You will also need the following KORE-specific credentials:

* Your Programmable Wireless SIM's SID or unique name. You can get this from the [**SIMs**](https://programmable-wireless.korewireless.com/wireless/sims) section of the Console.
* Your Authorization Token is available from your [console dashboard](https://build.korewireless.com) .

Copy the following code and paste it into a command line, then edit it to add your own credentials where marked. Make sure you remove the angle brackets. Windows users may need to remove the `\` symbols and run the command on a single line:

```bash
curl -X POST `https://programmable-wireless.api.korewireless.com/v1/Commands` \
  --data-urlencode "Sim=<YOUR_SIM_SID_OR_NAME>" \
  --data-urlencode "Command=hello_sim" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --header "Authorization: Bearer <YOUR_AUTH_TOKEN>"
```

This code creates a Command resource in the KORE cloud which then triggers the transmission of the `Command` field's value to the specified SIM.

On your computer, you'll see the JSON results of the `POST` you sent to KORE via *curl*. Shortly, you'll receive the Command itself on your device from the 2936 number.

Again, you can verify that the Command was received by following the procedure described above, or you can check on the device itself if it has a suitable interface:

We've used a non-IoT device, of course, but it demonstrates how your cloud will send Commands to your IoT device. Here's the flow in this case:<br>

<figure><img src="https://3566848590-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9p1Cs774U7DhQF5Pc3aj%2Fuploads%2FigNHtlnpWEVX30am6Dl2%2Fimage.png?alt=media&#x26;token=4a21d312-cd4b-406c-aeab-e34bf180259e" alt=""><figcaption></figcaption></figure>

* Your cloud-side app embeds the command in a request it sends to&#x20;

  ```url
  https://programmable-wireless.api.korewireless.com/v1/Commands
  ```
* KORE decodes the request, authorizes the access, and creates a Command resource.
* The Command resource sends the command itself to the IoT device as an SMS.
* Your IoT device's cellular module receives the command in SMS and your device-side application processes it.

### Need some help?