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

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.

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.

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.

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

  Expand image

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:

   Expand image

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:

   Expand image

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:

   Expand image

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

   Expand image

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.

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

Expand image

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.