Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Command Resource


The Command resource enables you to exchange simple 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.


Asynchronous resources

asynchronous-resources page anchor

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.


Property nameTypePIIDescription
sidSID<DC>
Not PII

The unique string that we created to identify the Command resource.

Pattern: ^DC[0-9a-fA-F]{32}$Min length: 34Max length: 34

account_sidSID<AC>

The SID of the Account that created the Command resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

sim_sidSID<DE>

The SID of the Sim resource that the Command was sent to or from.

Pattern: ^DE[0-9a-fA-F]{32}$Min length: 34Max length: 34

commandstring
PII MTL: 30 days

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.


command_modeenum<string>

The mode used to send the SMS message. Can be: text or binary. The default SMS mode is text.

Possible values:
textbinary

transportenum<string>

The type of transport used. Can be: sms or ip.

Possible values:
smsip

delivery_receipt_requestedboolean

Whether to request a delivery receipt.


statusenum<string>

The status of the Command. Can be: queued, sent, delivered, received, or failed. See Status Values for a description of each state.

Possible values:
queuedsentdeliveredreceivedfailed

directionenum<string>

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.

Possible values:
from_simto_sim

date_updatedstring<date-time>

The date and time in GMT when the resource was last updated specified in ISO 8601(link takes you to an external page) format.


urlstring<uri>

The absolute URL of the resource.

Status values

status-values page anchor
StatusDescription
queuedThe Command is queued in our network waiting to be sent to the SIM.
sentThe Command has been sent to the SIM.
deliveredThe Command has been delivered to the SIM. For to_sim Commands only.
receivedThe Command has been received from the SIM. For from_sim Commands only.
failedThe Command has failed to be transmitted.

Create a Command resource

create-a-command-resource page anchor
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:

ParameterDescription
CommandSidThe Command this callback is in reference to.
CommandStatusThe current status of the Command.
SimSidThe SIM this Command was sent to.
SimUniqueNameThe receiving SIM's UniqueName, if it has one.
ErrorCodeIf an error occurred, an error code is provided.
ErrorMessageIf an error occurred, an error message is provided.
ApiVersionThe version of the API that your initial request was made to.
AccountSidThe SID of the Account that this Command belongs to.
CommandModeA 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.

Property nameTypeRequiredPIIDescription
Commandstringrequired

The message body of the Command. Can be plain text in text mode or a Base64 encoded byte string in binary mode.


SimstringOptional

The sid or unique_name of the SIM to send the Command to.


CallbackMethodenum<http-method>Optional

The HTTP method we use to call callback_url. Can be: POST or GET, and the default is POST.

Possible values:
GETPOST

CallbackUrlstring<uri>Optional

The URL we call using the callback_url when the Command has finished sending, whether the command was delivered or it failed.


CommandModeenum<string>Optional

The mode to use when sending the SMS message. Can be: text or binary. The default SMS mode is text.

Possible values:
textbinary

IncludeSidstringOptional

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.


DeliveryReceiptRequestedbooleanOptional

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.

Create a text Command resource

create-a-text-command-resource page anchor

Send the ‘wakeup' command to the ‘AliceSmithSmartMeter' SIM

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
import twilio from "twilio";
_15
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = twilio(accountSid, authToken);
_15
_15
const command = await client.wireless.v1.commands.create({
_15
command: "wakeup",
_15
sim: "AliceSmithSmartMeter",
_15
});
_15
_15
console.log(command.sid);

Output

_14
{
_14
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_14
"command": "wakeup",
_14
"command_mode": "text",
_14
"date_created": "2015-07-30T20:00:00Z",
_14
"date_updated": "2015-07-30T20:00:00Z",
_14
"delivery_receipt_requested": true,
_14
"sim_sid": "DEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_14
"direction": "from_sim",
_14
"sid": "DCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_14
"status": "queued",
_14
"transport": "sms",
_14
"url": "https://wireless.twilio.com/v1/Commands/DCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_14
}

Create a binary Command resource

create-a-binary-command-resource page anchor

Send a binary command to the ‘AliceSmithSmartMeter' SIM

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_16
// Download the helper library from https://www.twilio.com/docs/node/install
_16
import twilio from "twilio";
_16
_16
// Find your Account SID and Auth Token at twilio.com/console
_16
// and set the environment variables. See http://twil.io/secure
_16
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16
const authToken = process.env.TWILIO_AUTH_TOKEN;
_16
const client = twilio(accountSid, authToken);
_16
_16
const command = await client.wireless.v1.commands.create({
_16
command: "SGVsbG8sIE1hY2hpbmUh==",
_16
commandMode: "binary",
_16
sim: "AliceSmithSmartMeter",
_16
});
_16
_16
console.log(command.sid);

Output

_14
{
_14
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_14
"command": "SGVsbG8sIE1hY2hpbmUh==",
_14
"command_mode": "binary",
_14
"date_created": "2015-07-30T20:00:00Z",
_14
"date_updated": "2015-07-30T20:00:00Z",
_14
"delivery_receipt_requested": true,
_14
"sim_sid": "DEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_14
"direction": "from_sim",
_14
"sid": "DCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_14
"status": "queued",
_14
"transport": "sms",
_14
"url": "https://wireless.twilio.com/v1/Commands/DCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_14
}


Fetch a Command resource

fetch-a-command-resource page anchor
GET https://wireless.twilio.com/v1/Commands/{Sid}

Property nameTypeRequiredPIIDescription
SidSID<DC>required

The SID of the Command resource to fetch.

Pattern: ^DC[0-9a-fA-F]{32}$Min length: 34Max length: 34
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
import twilio from "twilio";
_14
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = twilio(accountSid, authToken);
_14
_14
const command = await client.wireless.v1
_14
.commands("DCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_14
.fetch();
_14
_14
console.log(command.sid);

Output

_14
{
_14
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_14
"command": "command",
_14
"command_mode": "text",
_14
"date_created": "2015-07-30T20:00:00Z",
_14
"date_updated": "2015-07-30T20:00:00Z",
_14
"delivery_receipt_requested": true,
_14
"sim_sid": "DEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_14
"direction": "from_sim",
_14
"sid": "DCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_14
"status": "queued",
_14
"transport": "sms",
_14
"url": "https://wireless.twilio.com/v1/Commands/DCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_14
}


Read multiple Command resources

read-multiple-command-resources page anchor
GET https://wireless.twilio.com/v1/Commands

(warning)

Warning

The maximum PageSize you can request when reading Commands is 100.

Property nameTypeRequiredPIIDescription
SimstringOptional

The sid or unique_name of the Sim resources to read.


Statusenum<string>Optional

The status of the resources to read. Can be: queued, sent, delivered, received, or failed.

Possible values:
queuedsentdeliveredreceivedfailed

Directionenum<string>Optional

Only return Commands with this direction value.

Possible values:
from_simto_sim

Transportenum<string>Optional

Only return Commands with this transport value. Can be: sms or ip.

Possible values:
smsip

PageSizeintegerOptional

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000

PageintegerOptional

The page index. This value is simply for client state.

Minimum: 0

PageTokenstringOptional

The page token. This is provided by the API.

Read multiple Command resources

read-multiple-command-resources-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_12
// Download the helper library from https://www.twilio.com/docs/node/install
_12
import twilio from "twilio";
_12
_12
// Find your Account SID and Auth Token at twilio.com/console
_12
// and set the environment variables. See http://twil.io/secure
_12
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_12
const authToken = process.env.TWILIO_AUTH_TOKEN;
_12
const client = twilio(accountSid, authToken);
_12
_12
const commands = await client.wireless.v1.commands.list({ limit: 20 });
_12
_12
commands.forEach((c) => console.log(c.sid));

Output

_12
{
_12
"commands": [],
_12
"meta": {
_12
"first_page_url": "https://wireless.twilio.com/v1/Commands?Status=queued&Direction=from_sim&Sim=sim&PageSize=50&Page=0",
_12
"key": "commands",
_12
"next_page_url": null,
_12
"page": 0,
_12
"page_size": 50,
_12
"previous_page_url": null,
_12
"url": "https://wireless.twilio.com/v1/Commands?Status=queued&Direction=from_sim&Sim=sim&PageSize=50&Page=0"
_12
}
_12
}


Delete a Command resource

delete-a-command-resource page anchor
DELETE https://wireless.twilio.com/v1/Commands/{Sid}

Property nameTypeRequiredPIIDescription
SidSID<DC>required

The SID of the Command resource to delete.

Pattern: ^DC[0-9a-fA-F]{32}$Min length: 34Max length: 34
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_12
// Download the helper library from https://www.twilio.com/docs/node/install
_12
import twilio from "twilio";
_12
_12
// Find your Account SID and Auth Token at twilio.com/console
_12
// and set the environment variables. See http://twil.io/secure
_12
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_12
const authToken = process.env.TWILIO_AUTH_TOKEN;
_12
const client = twilio(accountSid, authToken);
_12
_12
await client.wireless.v1
_12
.commands("DCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_12
.remove();


Receive a Command from a SIM

receive-a-command-from-a-sim page anchor

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.

ParameterDescription
CommandSidThe SID of this Command.
SimSidThe SIM this Command was sent by.
SimUniqueNameThe sending SIM's friendly name, if it has one.
CommandThe 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.
StatusWill always be the string received.
ApiVersionThe version of the API that your initial request was made to.
AccountSidThe SID of the Account that this Command belongs to.
CommandModeA string representing which mode the SMS was received as. May be text or binary.

Rate this page: