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?

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 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.

Send a Command from your device

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 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 .

3. Send an SMS to the short code 2936.

What is this 2936 number?

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

• Navigate to the 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:

  

Relay messages to your cloud

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 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:

   
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:

1. Keep the tab open.

2. Go back to the web browser tab showing the KORE Console and paste the URL into the Commands Callback URL field.

3. Click Save .

4. 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:

1. Click on it to see the request body, then on the JSON icon, {:}, to view the data more clearly:

   

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

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.

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 section of the Console.

• Your Authorization Token is available from your console dashboard .

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:

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:

• Your cloud-side app embeds the command in a request it sends to

  Copy

  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?