The Command resource enables you to exchange machine-to-machine messages with SMS-capable devices. For example, you could use a Command resource to instruct a device to take a sensor reading.
While SMS is used as the transport, the SIM does not require an addressable phone number to receive a Command. This is the major distinction from Twilio's Messages resource, which can be used for conversational messaging.
Any SMS message sent from a SIM to a pre-determined phone number — see Receive a Command from a SIM — is interpreted as a Command and sent to the Command callback URL of the Sim resource.
Commands can be sent and received using the SMS text mode or binary (PDU) mode. Text-mode Commands have a maximum length of 160 single-byte characters. Binary-mode Commands have a maximum length of 140 bytes.
To receive and process a Command sent to your device, you will interface with the modem directly, probably using AT commands. You should consult with the module manufacturer's documentation for information about receiving SMS messages.
The Command resource performs asynchronous operations. To receive an asynchronous notification when a Command resource has finished updating, provide a callback URL, and optionally a callback method, GET
or POST
, when you create the Command.
Commands are retained for 30 days from the time they are created. Commands older than 30 days will no longer be readable from this resource.
The unique string that we created to identify the Command resource.
^DC[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The SID of the Account that created the Command resource.
^AC[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The SID of the Sim resource that the Command was sent to or from.
^DE[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The message being sent to or from the SIM. For text mode messages, this can be up to 160 characters. For binary mode messages, this is a series of up to 140 bytes of data encoded using base64.
The mode used to send the SMS message. Can be: text
or binary
. The default SMS mode is text
.
text
binary
The type of transport used. Can be: sms
or ip
.
sms
ip
The status of the Command. Can be: queued
, sent
, delivered
, received
, or failed
. See Status Values for a description of each state.
queued
sent
delivered
received
failed
The direction of the Command. Can be to_sim
or from_sim
. The value of to_sim
is synonymous with the term mobile terminated
, and from_sim
is synonymous with the term mobile originated
.
from_sim
to_sim
The date and time in GMT when the resource was created specified in ISO 8601 format.
The date and time in GMT when the resource was last updated specified in ISO 8601 format.
The absolute URL of the resource.
Status | Description |
---|---|
queued | The Command is queued in our network waiting to be sent to the SIM. |
sent | The Command has been sent to the SIM. |
delivered | The Command has been delivered to the SIM. For to_sim Commands only. |
received | The Command has been received from the SIM. For from_sim Commands only. |
failed | The Command has failed to be transmitted. |
POST https://wireless.twilio.com/v1/Commands
Creating a Command resource sends the command
to the SIM.
Outgoing Command delivery is asynchronous, so we recommend that you pass a callback URL when you create the new Command.
When you provide a callback URL, we call it when the attempt to send the Command completes.
We send these parameters to the callback URL:
Parameter | Description |
---|---|
CommandSid | The Command this callback is in reference to. |
CommandStatus | The current status of the Command. |
SimSid | The SIM this Command was sent to. |
SimUniqueName | The receiving SIM's UniqueName, if it has one. |
ErrorCode | If an error occurred, an error code is provided. |
ErrorMessage | If an error occurred, an error message is provided. |
ApiVersion | The version of the API that your initial request was made to. |
AccountSid | The SID of the Account that this Command belongs to. |
CommandMode | A string representing which mode the SMS was sent using. May be text or binary . |
If the CallbackMethod
parameter was set to POST,
or not provided, the callback parameters are delivered as HTML form parameters. If the CallbackMethod
parameter was set to GET
, the callback parameters are delivered as a query string.
application/x-www-form-urlencoded
The message body of the Command. Can be plain text in text mode or a Base64 encoded byte string in binary mode.
The HTTP method we use to call callback_url
. Can be: POST
or GET
, and the default is POST
.
GET
POST
The URL we call using the callback_url
when the Command has finished sending, whether the command was delivered or it failed.
The mode to use when sending the SMS message. Can be: text
or binary
. The default SMS mode is text
.
text
binary
Whether to include the SID of the command in the message body. Can be: none
, start
, or end
, and the default behavior is none
. When sending a Command to a SIM in text mode, we can automatically include the SID of the Command in the message body, which could be used to ensure that the device does not process the same Command more than once. A value of start
will prepend the message with the Command SID, and end
will append it to the end, separating the Command SID from the message body with a space. The length of the Command SID is included in the 160 character limit so the SMS body must be 128 characters or less before the Command SID is included.
Whether to request delivery receipt from the recipient. For Commands that request delivery receipt, the Command state transitions to 'delivered' once the server has received a delivery receipt from the device. The default value is true
.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createCommand() {11const command = await client.wireless.v1.commands.create({12command: "wakeup",13sim: "AliceSmithSmartMeter",14});1516console.log(command.sid);17}1819createCommand();
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"command": "wakeup",4"command_mode": "text",5"date_created": "2015-07-30T20:00:00Z",6"date_updated": "2015-07-30T20:00:00Z",7"delivery_receipt_requested": true,8"sim_sid": "DEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",9"direction": "from_sim",10"sid": "DCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",11"status": "queued",12"transport": "sms",13"url": "https://wireless.twilio.com/v1/Commands/DCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"14}
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createCommand() {11const command = await client.wireless.v1.commands.create({12command: "SGVsbG8sIE1hY2hpbmUh==",13commandMode: "binary",14sim: "AliceSmithSmartMeter",15});1617console.log(command.sid);18}1920createCommand();
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"command": "SGVsbG8sIE1hY2hpbmUh==",4"command_mode": "binary",5"date_created": "2015-07-30T20:00:00Z",6"date_updated": "2015-07-30T20:00:00Z",7"delivery_receipt_requested": true,8"sim_sid": "DEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",9"direction": "from_sim",10"sid": "DCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",11"status": "queued",12"transport": "sms",13"url": "https://wireless.twilio.com/v1/Commands/DCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"14}
GET https://wireless.twilio.com/v1/Commands/{Sid}
The SID of the Command resource to fetch.
^DC[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchCommand() {11const command = await client.wireless.v112.commands("DCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.fetch();1415console.log(command.sid);16}1718fetchCommand();
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"command": "command",4"command_mode": "text",5"date_created": "2015-07-30T20:00:00Z",6"date_updated": "2015-07-30T20:00:00Z",7"delivery_receipt_requested": true,8"sim_sid": "DEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",9"direction": "from_sim",10"sid": "DCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",11"status": "queued",12"transport": "sms",13"url": "https://wireless.twilio.com/v1/Commands/DCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"14}
GET https://wireless.twilio.com/v1/Commands
The maximum PageSize
you can request when reading Commands is 100.
The status of the resources to read. Can be: queued
, sent
, delivered
, received
, or failed
.
queued
sent
delivered
received
failed
Only return Commands with this direction value.
from_sim
to_sim
Only return Commands with this transport value. Can be: sms
or ip
.
sms
ip
How many resources to return in each list page. The default is 50, and the maximum is 1000.
1
Maximum: 1000
The page token. This is provided by the API.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listCommand() {11const commands = await client.wireless.v1.commands.list({ limit: 20 });1213commands.forEach((c) => console.log(c.sid));14}1516listCommand();
1{2"commands": [],3"meta": {4"first_page_url": "https://wireless.twilio.com/v1/Commands?Status=queued&Direction=from_sim&Sim=sim&PageSize=50&Page=0",5"key": "commands",6"next_page_url": null,7"page": 0,8"page_size": 50,9"previous_page_url": null,10"url": "https://wireless.twilio.com/v1/Commands?Status=queued&Direction=from_sim&Sim=sim&PageSize=50&Page=0"11}12}
DELETE https://wireless.twilio.com/v1/Commands/{Sid}
The SID of the Command resource to delete.
^DC[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function deleteCommand() {11await client.wireless.v112.commands("DCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.remove();14}1516deleteCommand();
To receive a Command from a SIM — called a "mobile-originated" Command — you should create or update an existing Sim instance and provide a CommandsCallbackUrl
property. Optionally, you may also include a CommandsCallbackMethod
property.
When a SIM sends an SMS message to the reserved phone number 2936
, a Command resource will be created, and your Commands Callback URL will be invoked. The callback request will include the following parameters.
Parameter | Description |
---|---|
CommandSid | The SID of this Command. |
SimSid | The SIM this Command was sent by. |
SimUniqueName | The sending SIM's friendly name, if it has one. |
Command | The body of the Command message. In text mode, this value can be up to 160 characters of text. In binary mode, this value is a Base64 encoded byte string with a maximum size of 140 bytes. |
Status | Will always be the string received . |
ApiVersion | The version of the API that your initial request was made to. |
AccountSid | The SID of the Account that this Command belongs to. |
CommandMode | A string representing which mode the SMS was received as. May be text or binary . |