Skip to contentSkip to navigationSkip to topbar
On this page

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?

how-are-commands-different-from-programmable-sms page anchor

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.

(information)

Info

You can get all the details you need to use Command resources in the Programmable Wireless API documentation.

(warning)

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.


Send a Command from your device

send-a-command-from-your-device page anchor

Let's say you want to send a Command from your device to Twilio'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?

what-is-this-2936-number page anchor

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

Verify that the target machine received the Command

verify-that-the-target-machine-received-the-command page anchor
  • 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

relay-messages-to-your-cloud page anchor

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(link takes you to an external page) 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(link takes you to an external page):

  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:

  4. Keep the tab open.

  5. Go back to the web browser tab showing the Twilio 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:

  8. 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 Twilio at 2936
  • Twilio POSTs 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

send-a-command-to-your-device page anchor

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(link takes you to an external page).

You will also need the following Twilio-specific credentials:

  • Your Programmable Wireless SIM's SID or unique name. You can get this from the SIMs section of the Console.
  • Your Account SID and Auth Token, both of which are 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:

1
curl -X POST https://wireless.twilio.com/v1/Commands \
2
--data-urlencode "Sim=<YOUR_SIM_SID_OR_NAME>" \
3
--data-urlencode "Command=hello_sim" \
4
-u <YOUR_ACCOUNT_SID>:<YOUR_AUTH_TOKEN>

This code creates a Command resource in the Twilio 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 Twilio 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:

Command received!.

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 https://wireless.twilio.com/v1/Commands.
  • Twilio 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?

Terms of service

Copyright © 2024 Twilio Inc.