Menu

Expand
Rate this page:

Get Started with Super SIM SMS Commands

SMS Commands is a new Super SIM API that will supersede the existing Commands API. Both were designed to allow you to exchange machine-to-machine (M2M) SMS messages with your Super SIM-connected devices, but SMS Commands more clearly indicates the transport mechanism used for message transfer. Look forward to further Commands APIs using other transports in future!

This short guide will show you how to set up and sample SMS Commands. Perhaps you’d like to see if it might be a useful addition to your application right now, or you’d like to see how it might be incorporated in the future. If you want to cut to the chase and start developing the feature into your application immediately, check out the full API documentation and sample code.

To demonstrate SMS Commands, we’ll use our current standard test rig, the same one we use in our Super SIM Quickstart. It comprises a Raspberry Pi 4 Linux computer and a Sixfab Cellular IoT add-on board, which incorporates a Quectel BG96 Cat-M1 cellular module. Please head over to the Super SIM Quickstart now for a list of the hardware you need and guidance on putting it together. When you’ve reached Step 4, you can choose to complete the Quickstart, or jump back here and finish the Quickstart later.

Insert the Super SIM into to Sixfab Cellular IoT Hat

This guide also requires a configured Super SIM. If you haven’t set up your Super SIM in the Console, please do so now. The Super SIM First Steps guide has help if you need it.

You can perform all of the following steps using the Raspberry Pi as both the target device and as a stand-in for your cloud or app. You can also use your main computer, but using the Pi saves moving between machines.

Send SMS Commands to the device

1. Prepare the device

To send or receive messages, first power up the device’s BG96 module.

  1. Check the Sixfab Cellular IoT Hat’s green STATUS LED — if it’s unlit, press the Hat’s PWRKEY button until it lights up. The blue NETLIGHT LED will begin flashing as the board’s BG96 talks to the network.
  2. By default, the Raspberry Pi will boot to the desktop. If it’s one you’ve used before and set to boot to the command line, just run startx to launch the desktop.
  3. Select Accessories > Terminal from the Raspberry menu.
  4. You’ll use a command-line serial console tool called Minicom to communicate with the BG96. If you would prefer to use an alternative tool, such as Screen, that’s fine, but it may have a slightly different device-selection procedure than the one outlined here.
  5. Enter minicom -D /dev/ttyUSB3 to open a connection to the BG96. If Minicom posts an error indicating that /dev/ttyUSB3 is inaccessible, please check your Cellular IoT Hat setup.
  6. The BG96 probably isn’t set to echo back what you type in, so you won’t be able to see your side of the conversation, so type in ATE1 and hit Enter. You’ll get an OK back, and when you follow the remaining steps you’ll see what you type.

2. Send an SMS Command to the device

Sending an SMS Command to the device is just a matter of making a POST request to the SMS Commands API endpoint, https://supersim.twilio.com/v1/SmsCommands. You need to provide your command, the SID of the Sim resource representing the Super SIM it’s being sent to, and of course your Twilio authorization details.

  1. Open a second LX Terminal instance on the Pi, or a terminal on your main machine.
  2. Let’s say this is the message you want to send to the device:

    { "command": "wake", "timestamp": "2021-04-19-15-03-49" }
    
    It’s a command encoded in JSON, though you can use any other textual format and with whatever combination of keys and values that’s appropriate for your application. The only restriction is that each Command can contain no more than 160 single-byte characters. You can send this message to your device using the curl command line tool as follows:

    curl -X POST https://supersim.twilio.com/v1/SmsCommands \
      --data-urlencode 'Sim=<YOUR_SIM_NAME_OR_SID>' \
      --data-urlencode 'Payload={"command":"wake","time":"2021-04-19-15-03-49"}' \
      -u <YOUR_ACCOUNT_SID>:<YOUR_AUTH_TOKEN>​
    
  3. Copy and paste the curl command to the command line then edit it to fill in the identifier of the Super SIM you’re using (you can get this from the Console if you don’t have it handy), and your account credentials (also available from the Console). The message is the value of the payload parameter.

The response, posted to the terminal by curl, will be a JSON string. It will include a number of fields, but look out for these two:

"status": "queued", 
"direction": "to_sim"

As you can see, the message’s status is queued: it’s in Twilio’s message queue waiting to be sent. When the SMS Command leaves the Twilio Mobile Core for the network the device is attached to, its status will become sent and then delivered when it has been confirmed by the network that the message was delivered. Later on, you’ll use a webhook, which you’ll set up in the next section, to receive notifications about message status changes as they happen.

You know your test device is connected to the cellular network, but a device in the field might not yet have connected when the message request was sent. If it’s a mobile device, it might have briefly passed out of cellular range. Consequently, Twilio will continue to attempt to send each new SMS Command for a period of up to 24 hours. If sending fails, the Command will remain in the queue. After 24 hours, it will be sent again, marked as failed and removed from the queue.

3. Read the SMS Command on the device

The message you just sent will probably already have arrived on the device, but you can check with an AT command sent to the cellular module. In the terminal running Minicom, enter AT+CSCS="IRA" and hit Enter. This tells the module to display characters in the International Reference Alphabet (IRA). We need this to view the braces in the JSON as they are not part of the standard GSM character set, which is the module’s default.

View an SMS Command on the target device

Now enter AT+CMGF=1 to set the BG96’s input mode to text, and then enter AT+CMGL="ALL" to list all of the SMS messages held on the device. Among them — or possibly the only one — you should see something like:

+CMGL: 0,"REC UNREAD","000",,
"21/04/19,15:04:26+00","{"command":"wake","time":"2021-04-19-15-03-49"}"

The first value after the command name (+CMGL:) is 0 here, but it might be a different number if your Super SIM has received other SMS messages before. This is this message’s index in the cellular module’s message store, and you can use it to read the specific message using it with this command:

AT+CMGR=<message_index>

Of course, a real-world application would handle these AT commands itself by taking directly to the cellular module. It would also parse the command embedded in the message and then perform the required action.

If you’re wondering what the "000" in the third parameter of the message listed above is, it’s Twilio’s SMS Commands number. All SMS Commands your devices receive will have come from this number, which you’ll now use to send a message back from the device.

Receive an SMS Command from the device

The SMS Commands API provides a specific phone number, 000, to which all SMS messages, from every device are sent. Twilio relays the ones it has received from your SIMs on to you. How does it know exactly where to send them? You specify a webhook address.

Super SIMs are organized into Fleets: groups of SIMs that have common settings, such as which networks they are able to connect to and whether they can make use of cellular data services. Fleets are represented in the Super SIM API by Fleet resources, and SMS Commands adds properties to each Fleet resource in which you can store your SMS Commands webhook address and, optionally, the HTTP method it uses.

So before you can send a message from the device, you need to set up a webhook target URL and add it to your Super SIM’s Fleet.

1. Set up a webhook target

Beeceptor is a handy service for testing webhooks. It’s designed for developing and testing APIs of your own, and 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 web browser tab, go to Beeceptor.
  2. Enter an endpoint name in the large text field and click Create Endpoint:
    Super SIM SMS Commands Beeceptor front
  3. On the screen that appears next, click on the upper of the two clipboard icons to copy the endpoint URL:
    Super SIM SMS Beeceptor endpoint
  4. Keep the tab open.

2. Update your Super SIM’s Fleet

Now you update your Super SIM’s Fleet to add an SMS Commands webhook. You can do this with the API, but we’ll use the Console for this demo.

  1. Open a second web browser tab and log into the Twilio Console.
  2. Go to IoT > Super SIM > Fleets and select the Fleet containing the Super SIM you are using.
  3. Scroll down to SMS Commands Callback URL and paste in your webhook URL from the previous section. By default, webhooks are triggered with a POST request. Leave it unchanged for now, but if you need to use another method for your own application, you can change it later:
    Super SMS Commands Console Webhook
  4. Click Save.
  5. Close the tab if you like.

3. Send an SMS Command from the device

  1. In the LX Terminal instance running Minicom — the one you’re using to talk to the BG96 — enter the following command:
    AT+CMGS="000"
    This tells the BG96 to read in what you’re going to type in next and then send it as an SMS message to the number 000.
  2. Minicom will now display a > prompt to show you that the BG96 is awaiting some text. Key in a Command — Super SIM says hi, for example — and then hold down the ctrl key and hit Z. The BG96 will attempt to send the Command, and you’ll see a readout of the number of characters sent and OK if it succeeded:
    Super SIM SMS Commands Minicom send message

4. Read the transmitted Command

  1. Jump back to the Beeceptor tab in the 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.
  2. Look for the line beginning Command= — right after it is the message you sent:
    Super SIM SMS Commands Beeceptor receipt 1

    You’ll also see that the Direction parameter now reads from_sim.

Monitor SMS Message transmission

The webhook URL you just put in place was set up to receive SMS Commands from the device. You can also use it in a tutorial context for monitoring messages being sent to the device. Using the same technique you applied in the Send messages to the device section, above, but this time add the following extra command to the curl call, replacing <YOUR_WEBHOOK_URL> with your Beeceptor endpoint.

--data-urlencode 'CallbackUrl=<YOUR_WEBHOOK_URL>'

This time, you’ll receive a series of notification messages as the SMS Command’s status moves from queued to sent to delivered:

Super SIM SMS Commands Beeceptor receipt 2

Next steps

You’ve set up a Quectel BG96 cellular modem to send and receive M2M SMS messages, and you’ve sent messages to the device and back again, all through Twilio Super SIM’s SMS Commands API. You’ve also used the API’s webhook mechanism to keep track of Command delivery.

The next stage, of course, is to build a device-side app that listens for commands, parses them and triggers actions accordingly. You may also want to create a server app that’s able to request information from devices: it sends a request command which causes the device to send a second, data-bearing message back. Or you might code up a mobile app that uses SMS Commands to control the device remotely.

We can’t wait to see what you build with Super SIM SMS Commands!

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting our Twilio Community forums or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more