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.
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.
You can get all the details you need to use Command resources in the Programmable Wireless API documentation.
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.
Let's say you want to send a Command from your device to Twilio's servers to either:
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:
Ready
or
Active
state
.
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.
You should see your first Command sent from a machine to a machine:
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.
In a fresh web browser tab, go to Beeceptor:
On the screen that appears next, click on the upper of the two clipboard icons to copy the endpoint URL:
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:
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:
POST
s a request containing the Command to your cloud at the specified endpoint.
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:
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:
1curl -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:
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:
https://wireless.twilio.com/v1/Commands
.