Command Resource

The Commands API below is being deprecated and will be later removed.

A new SMS Commands API has been added for exchanging machine-to-machine SMS with your Super SIM-connected devices. Please plan to migrate your integrations to use the new SMS Commands API as soon as possible. We expect to end support for the Commands API on September 15, 2021.

The functionality offered by the SMS Commands and Commands APIs is almost identical. Some property names have been modified: for example, the command property is now payload. The new SMS Commands API was introduced to make the machine-to-machine SMS functionality more easily discoverable by adding the transport mechanism to the name. It also allows for the introduction of similar APIs that use different transport mechanisms to send messages to Super SIMs via a REST API under a common “Commands” moniker.

Beta

Commands for Super SIM is currently in Public Beta and will not transition to General Availability before being removed from the API. Beta products are not covered by a Twilio SLA. Learn more about beta product support.

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.

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

Commands to SIM (Mobile Terminated)

SMS Commands sent to your device, also known as Mobile Terminated (MT) commands, are initiated by making a POST request to the Commands API endpoint. The Command will be sent to your SIM asynchronously. When the Command API is invoked to send an SMS Command to your device, a Command resource will be created with status queued. Learn more about the Command states in the Status section below.

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

Commands API will attempt to send a Command 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 Command was sent. The Command resource will remain in queued status until the first attempt to send it and in sent status after the first attempt. The status will change to delivered once there is delivery confirmation. If there is no delivery confirmation within the 24 hour period, the status will stay as sent.

You can receive callbacks to a defined URL by providing a callback URL and callback method in your POST request. You will receive a HTTP request to that callback URL each time the status is updated.

https://supersim.twilio.com/v1/Commands

Commands from SIM (Mobile Originated)

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

Currently all SMS regardless of the number to which they were sent are treated as 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.

You can be programmatically notified that an SMS Command has been received from your device (Mobile Originated) by configuring a webhook on your Super SIM’s Fleet resource.

Asynchronous resource

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 parameter, when you create the Command.

Command properties

Resource Properties in REST API format
`sid`	sid<HC> Not PII The unique string that we created to identify the Command resource.
`account_sid`	sid<AC> Not PII The SID of the Account that created the Command resource.
`sim_sid`	sid<HS> Not PII The SID of the SIM that this Command was sent to or from.
`command`	string PII MTL: 30 DAYS The message body of the command sent to or from the SIM. For text mode messages, this can be up to 160 characters.
`status`	enum:status Not PII The status of the Command. Can be: `queued`, `sent`, `delivered`, `received` or `failed`. See the Command Status Values for a description of each.
`direction`	enum:direction Not PII 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`.
`date_created`	date_time<iso8601> Not PII The date and time in GMT when the resource was created specified in ISO 8601 format.
`date_updated`	date_time<iso8601> Not PII The date and time in GMT when the resource was last updated specified in ISO 8601 format.
`url`	url Not PII The absolute URL of the Command resource.

Command Resource Status Callbacks

The user can provide a callback method and callback URL to receive updates each time a Command to their device’s status changes.

`AccountSid`	The SID of the Account that the Command resource belongs to.
`CommandSid`	The unique string that we created to identify the Command resource.
`SimSid`	The receiving Super SIM’s `SID`
`SimUniqueName`	The receiving Super SIM’s `UniqueName`.
`Command`	Warning: This value will no longer be sent after this resource is deprecated. Read the value from the `Payload` property. The body of the Command message. This value can be up to 160 characters of text. Binary mode is not supported. Contains the same value as the `Payload`.
`Payload`	The body of the Command message. This value can be up to 160 characters of text. Binary mode is not supported. Contains the same value as the `Command`.
`Direction`	Indicates whether it is an MT/MO Command. It has two possible values - `to_sim` or `from_sim`.
`Status`	The delivery status of the Command.
`ErrorCode`	The error code (if any) associated with your Command. Unless the status is `failed`, `ErrorCode` will not be present.
`ErrorMessage`	Description of the error. Unless the status is `failed`, `ErrorMessage` will not be present.

Status Values

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

`queued`	The Command is queued in our network waiting to be sent
`sent`	The Command has been sent to the SIM
`delivered`	The Command has been delivered to the SIM and there was a delivery confirmation from the device
`received`	The Command has been received from the SIM
`failed`	The Command could not be sent

Create a Command resource

post

https://supersim.twilio.com/v1/Commands

Parameters

Parameters in REST API format
`sim` Required	post sid<HS> Not PII The `sid` or `unique_name` of the SIM to send the Command to.
`command` Required	post string PII MTL: 30 DAYS The message body of the command.
`callback_method` Optional	post http_method Not PII The HTTP method we should use to call `callback_url`. Can be: `GET` or `POST` and the default is POST.
`callback_url` Optional	post url Not PII The URL we should call using the `callback_method` after we have sent the command.

Example 1

Loading Code Sample...

Show sample response

Example JSON response

Show code

Create Command

Fetch a Command resource

get

https://supersim.twilio.com/v1/Commands/{Sid}

Parameters

Parameters in REST API format
`sid` Path	get sid<HC> Not PII The SID of the Command resource to fetch.

Parameters in REST API format

sid

Path

get sid<HC> Not PII

The SID of the Command resource to fetch.

Example 1

Loading Code Sample...

Show sample response

Example JSON response

Show code

Fetch Command

Read multiple Command resources

get

https://supersim.twilio.com/v1/Commands

Parameters

Parameters in REST API format
`sim` Optional	get sid_like<HS> Not PII The SID or unique name of the Sim that Command was sent to or from.
`status` Optional	get ienum:status Not PII The status of the Command. Can be: `queued`, `sent`, `delivered`, `received` or `failed`. See the Command Status Values for a description of each.
`direction` Optional	get ienum:direction Not PII 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`.

Parameters in REST API format

sim

Optional

get sid_like<HS> Not PII

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

status

Optional

get ienum:status Not PII

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

direction

Optional

get ienum:direction Not PII

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.

Example 1

Loading Code Sample...

Show sample response

Example JSON response

Show code

Read Command

Receive a Command from a SIM

To receive a Command (Mobile Originated) from a SIM, you should create or update an existing Fleet instance and provide a CommandsUrl property, and optionally a CommandsMethod property.

When a SIM sends an SMS message to the reserved phone number 000, a Command resource will be created and your Commands URL will be invoked. The Callback request will include the same parameters as the Commands Status Callbacks

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 Twilio's Community Forums or browsing the Twilio tag on Stack Overflow.

Parameters

Example 1

Parameters

Example 1

Parameters

Example 1

Need some help?

Thank you for your feedback!

Thanks for your feedback!

Step 1

Step 2

Step 3