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

SMSCommand Resource


(warning)

Public Beta

Super SIM's SMS Commands API is currently in Public Beta . Some features are not yet implemented and others may be changed before the product is declared as Generally Available. Beta products are not covered by a Twilio SLA . Learn more about beta product support(link takes you to an external page).

To avoid ambiguity throughout this page, Sim (initial cap) refers to the Sim API resource. SIM (all caps) refers to the physical Subscriber Identity Module (that is, a SIM card) associated with a Sim resource.

SMS Commands enable you to exchange simple machine-to-machine (M2M) messages with devices over SMS. In order to use SMS Commands, devices must be capable of receiving and sending SMS messages. The SIM does not require an addressable phone number to send or receive a SMS Command. SMS Commands have a maximum length of 160 single-byte characters.

(information)

Info

If you'd like to try SMS Commands out straight away, check out our Get Started guide. Or read on for the full API documentation.


SMS Commands to SIM (Mobile Terminated)

sms-commands-to-sim-mobile-terminated page anchor

SMS Commands sent to your device, also known as Mobile Terminated (MT) SMS Commands, are initiated by making a POST request to the SMS Commands API endpoint:


_10
https://supersim.twilio.com/v1/SmsCommands

The SMS will be sent to your SIM asynchronously. When the SMS Command API is invoked to send an SMS Command to your device, a SMS Command resource will be created with status queued. Learn more about the SMS Command states in the Status section below.

The SMS received by your device will always be from the number 000. There is no publicly addressable phone number for your Super SIM. The only way to reach it via SMS is by using the SMS Commands API.

The SMS Commands API will continue to attempt to send an SMS to your Super SIM-powered device for up to 24 hours. This is to account for cases where your device has not yet come online when your request to send an SMS Command was submitted. The status of the SMS Command resource will remain as queued until the first attempt to send it, after which its status will become sent. The command's status will change to delivered once there its delivery has been confirmed. If there is no delivery confirmation within the 24-hour period, the status will stay sent.

You can receive status change notifications by providing a callback URL and method in your POST request. You will receive an HTTP request to that callback URL each time the command's status changes.


SMS Commands from SIM (Mobile Originated)

sms-commands-from-sim-mobile-originated page anchor

All SMS sent from your device to 000 will be treated as SMS Commands. The status for all Mobile Originated (MO) SMS Commands will always be received.

You can be automatically notified when an SMS is received from your Super SIM connected device by configuring the sms_commands_url and sms_commands_method properties of the Fleet resource to which the Sim resource has been assigned. When your Super SIM-connected device sends an SMS message to the reserved number 000, an SMS Command resource will be created and your Fleet resource's sms_commands_url will be sent a notification. The request made to your URL will include the same parameters as the SMS Commands Status Callback.

(warning)

Warning

Currently all SMS, regardless of the number to which they were sent, are treated as SMS Commands, not just those sent to 000. This may change in the future. To ensure that there is no interruption to your services if this changes, all SMS you wish to be treated as Commands should be sent to 000.


The SMS Command resource performs asynchronous operations. To receive an asynchronous notification when a SMS Command resource has finished updating, provide a callback URL, and optionally a callback method parameter, when you create the SMS Command.


SMS Commands are retained for 30 days from the time they are created. SMS Commands older than 30 days will no longer be readable from this resource.

(information)

Info

Customers may request that SMS Command data be deleted. If you wish to do so, please contact Twilio Support through the Console(link takes you to an external page) or Help Center(link takes you to an external page). For more information on Twilio's data retention and deletion policy, please see this support document(link takes you to an external page).


Property nameTypePIIDescription
sidSID<HC>
Not PII

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

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

account_sidSID<AC>

The SID of the Account that created the SMS Command resource.

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

sim_sidSID<HS>

The SID of the SIM that this SMS Command was sent to or from.

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

payloadstring
PII MTL: 30 days

The message body of the SMS Command sent to or from the SIM. For text mode messages, this can be up to 160 characters.


statusenum<string>

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

Possible values:
queuedsentdeliveredreceivedfailed

directionenum<string>

The direction of the SMS 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:
to_simfrom_sim

date_createdstring<date-time>

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


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 SMS Command resource.

Status values

status-values page anchor

When the API is used to send an SMS to your device, the SMS Command resource status will be set to the statues queued. The Status property will be updated to sent when an SMS is sent from Twilio Mobile Core to the cellular network to which your device is connected (the 'visited' network). If a delivery receipt (DLR) is received from your device, the status will be updated to delivered. If at any point this process fails and the Command is no longer deliverable, the status will be updated to failed and an error code will be indicated on the resource.

queuedThe SMS Command is queued in our network waiting to be sent.
sentThe SMS Command has been sent to the SIM.
deliveredThe SMS Command has been delivered to the SIM and there was a delivery confirmation from the device.
receivedThe SMS Command has been received from the SIM.
failedThe SMS Command could not be sent.

SMS Command resource status callbacks

sms-command-resource-status-callbacks page anchor

You can provide a callback method and callback URL to receive updates each time a SMS Command to your device's status changes. The request sent to the callback URL contains the following properties:

AccountSidThe SID of the Account that the SMS Command resource belongs to.
CommandSidThe unique string that we created to identify the SMS Command resource.
SimSidThe receiving Super SIM's SID.
SimUniqueNameThe receiving Super SIM's UniqueName.
PayloadThe body of the SMS Command message. This value can be up to 160 characters of text. Binary mode is not supported.
DirectionIndicates whether the Command is MT or MO. It has two possible values: to_sim or from_sim.
StatusThe delivery status of the SMS Command.
ErrorCodeThe error code (if any) associated with a failed SMS Command. Unless the status is failed, ErrorCode will not be present.
ErrorMessageA description of the error (if any) associated with a failed SMS Command. Unless the status is failed, ErrorMessage will not be present.

Create a SmsCommand resource

create-a-smscommand-resource page anchor
POST https://supersim.twilio.com/v1/SmsCommands

Property nameTypeRequiredPIIDescription
Simstringrequired

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


Payloadstringrequired

The message body of the SMS Command.


CallbackMethodenum<http-method>Optional

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

Possible values:
GETPOST

CallbackUrlstring<uri>Optional

The URL we should call using the callback_method after we have sent the command.

Create Sms Command

create-sms-command page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.supersim.v1.smsCommands
_10
.create({sim: 'sim', payload: 'payload'})
_10
.then(sms_command => console.log(sms_command.sid));

Output

_11
{
_11
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_11
"payload": "checkin: firmware update",
_11
"date_created": "2015-07-30T20:00:00Z",
_11
"date_updated": "2015-07-30T20:00:00Z",
_11
"sim_sid": "HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_11
"sid": "HCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_11
"status": "queued",
_11
"direction": "to_sim",
_11
"url": "https://supersim.twilio.com/v1/SmsCommands/HCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_11
}


Fetch a SmsCommand resource

fetch-a-smscommand-resource page anchor
GET https://supersim.twilio.com/v1/SmsCommands/{Sid}

Property nameTypeRequiredPIIDescription
SidSID<HC>required

The SID of the SMS Command resource to fetch.

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

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.supersim.v1.smsCommands('HCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.fetch()
_10
.then(sms_command => console.log(sms_command.sid));

Output

_11
{
_11
"sid": "HCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_11
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_11
"payload": "content of the command",
_11
"sim_sid": "HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_11
"status": "queued",
_11
"direction": "to_sim",
_11
"date_created": "2015-07-30T20:00:00Z",
_11
"date_updated": "2015-07-30T20:00:00Z",
_11
"url": "https://supersim.twilio.com/v1/SmsCommands/HCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_11
}


Read multiple SmsCommand resources

read-multiple-smscommand-resources page anchor
GET https://supersim.twilio.com/v1/SmsCommands

(warning)

Warning

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

Property nameTypeRequiredPIIDescription
SimstringOptional

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


Statusenum<string>Optional

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

Possible values:
queuedsentdeliveredreceivedfailed

Directionenum<string>Optional

The direction of the SMS 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:
to_simfrom_sim

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.

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

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.supersim.v1.smsCommands
_10
.list({limit: 20})
_10
.then(smsCommands => smsCommands.forEach(s => console.log(s.sid)));

Output

_24
{
_24
"meta": {
_24
"first_page_url": "https://supersim.twilio.com/v1/SmsCommands?Status=received&Sim=HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&PageSize=50&Page=0",
_24
"key": "sms_commands",
_24
"next_page_url": "https://supersim.twilio.com/v1/SmsCommands?Status=received&Sim=HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&PageSize=50&Page=1",
_24
"page": 0,
_24
"page_size": 50,
_24
"previous_page_url": "https://supersim.twilio.com/v1/SmsCommands?Status=received&Sim=HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&PageSize=50&Page=0",
_24
"url": "https://supersim.twilio.com/v1/SmsCommands?Status=received&Sim=HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&PageSize=50&Page=0"
_24
},
_24
"sms_commands": [
_24
{
_24
"sid": "HCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"payload": "content of the command",
_24
"sim_sid": "HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"status": "received",
_24
"direction": "from_sim",
_24
"date_created": "2015-07-30T20:00:00Z",
_24
"date_updated": "2015-07-30T20:00:00Z",
_24
"url": "https://supersim.twilio.com/v1/SmsCommands/HCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_24
}
_24
]
_24
}


Rate this page: