Menu

Expand
Rate this page:

Thanks for rating this page!

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

REST API: Commands

The Commands resource enables you to exchange simple machine-to-machine messages with SMS-capable devices. For example, you could use a Command to instruct a device to change its APN.

SMS is used as the transport but 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 Commands Callback Url of the SIM.

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 when that is sent to your device, you will interface with the modem directly, probably using 'AT Commands'. You should consult with the GSM/LTE module manufacturer's documentation on receiving SMS messages.

Common Tasks

Asynchronous Resources

The Command resource performs Asynchronous Operations. To receive an asynchronous notification when a Command resource has finished updating, you should provide a callback URL and optionally a callback method parameter with your initial HTTP Request. This is demonstrated in some of the examples below.

HTTP Resources and Methods

Command Instance Resource

Resource URLs

https://wireless.twilio.com/v1/Commands/{CommandSid}

Resource Properties

A Command instance resource is represented by the following properties:

Names in PHP format
sid
sid<DC> Not PII

A 34 character string that uniquely identifies this resource.

accountSid
sid<AC> Not PII

The unique id of the Account that this Command belongs to.

simSid
sid<DE> Not PII

The unique ID of the SIM that this Command was sent to or from.

command

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.

commandMode
enum:command_mode Not PII

A string representing which mode the SMS was sent or received using. May be text or binary.

transport
enum:transport Not PII

deliveryReceiptRequested
boolean Not PII

status
enum:status Not PII

A string representing the status of the Command. May be queued, sent, delivered, received or failed. See Status Values for a description of each state.

direction
enum:direction Not PII

The direction of the Command. May be to_sim or from_sim. to_sim is synonymous with the term mobile terminated, from_sim is synonymous with the term mobile originated.

dateCreated
date_time<iso8601> Not PII

The date that this resource was created, given as GMT in ISO 8601 format.

dateUpdated
date_time<iso8601> Not PII

The date that this resource was last updated, given as GMT in ISO 8601 format.

url
url Not PII

The URL for this resource.

Status Values

The table below describes the available status values of a Command instance.

Status Description
queued The Command is queued in Twilio’s 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.)
received The Command has been received from the SIM. (For from_sim Commands.)
failed The Command has failed.

HTTP GET

Returns a representation of the Command.

Example

Request a Command instance using its Sid, represented as JSON.

        
        
        
        

        HTTP POST

        Not supported.

        HTTP PUT

        Not supported.

        HTTP DELETE

        Delete a Command from your account.

        Commands List Resource

        Resource URL

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

        HTTP GET

        Returns a list of Commands within an account. The list includes paging information.

        Example 1

        List all Commands in the account.

              
              
              
              
              List Filters

              The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive:

              Names in PHP format
              sim
              Optional
              get string Not PII

              Only return Commands to or from this SIM.

              status
              Optional
              get enum:status Not PII

              Only return Commands with this status value.

              direction
              Optional
              get enum:direction Not PII

              Only return Commands with this direction value.

              transport
              Optional
              get enum:transport Not PII

              Only return Commands with this transport value.

              HTTP POST

              You can create a new Command resource by POSTing to the Commands list resource. This is synonymous with sending a Command to a SIM.

              Parameters
              Names in PHP format
              command
              Required
              post string PII MTL: 30 DAYS

              The message body of the Command (in text mode) or a Base64 encoded byte string in binary mode.

              sim
              Optional
              post string Not PII

              The Sid or UniqueName of the SIM to send the Command to.

              callbackMethod
              Optional
              post http_method Not PII

              The HTTP method Twilio will use when making a request to the callback URL (valid options are GET or POST). Defaults to POST.

              callbackUrl
              Optional
              post url Not PII

              Twilio will make a request to this URL when the Command has finished sending (delivered or failed).

              commandMode
              Optional
              post enum:command_mode Not PII

              A string representing which mode to send the SMS message using. May be text or binary. If omitted, the default SMS mode is text.

              includeSid
              Optional
              post string Not PII

              When sending a Command to a SIM in text mode, Twilio 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. The options for inclusion are none, start and end. The default behavior is none. When using start or end, the CommandSid will be prepended or appended to the message body, with a space character separating the CommandSid and the message body. The length of the CommandSid contributes toward the 160 character limit, i.e. the SMS body must be 128 characters or less before the Command Sid is included.

              deliveryReceiptRequested
              Optional
              post boolean Not PII

              A boolean representing 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. Defaults to true.

              Callback Values

              Outgoing Command delivery is asynchronous, so it is recommended to pass a callback URL which is called when the attempt to send the Command has completed. Callbacks will contain the following parameters:

              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 unique id 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 callback method was set to POST or not provided, the callback parameters will be delivered as HTML form parameters. If the callback method was set to GET, the callback parameters will be delivered as a query string.

              Example

              Send a Command to a SIM. Provide a callback URL and callback method to be asynchronously notified when the Command delivery attempt has completed. In this example we use the SIM UniqueName 'AliceSmithSmartMeter' to identify the receiving SIM.

              Commands sent from SIMs in ready status

              A Command can be sent from a SIM in the ready status. Following the fifth Command sent to_sim or from_sim the device will automatically transition to the active status. Visit the SIM Status Values to learn more.

                    
                    
                    
                    
                          
                          
                          
                          

                          HTTP PUT

                          Not supported.

                          HTTP DELETE

                          Not supported.

                          Receive a Command from a SIM

                          To receive a Command from a SIM ('mobile-originated'), you should create or update an existing SIM instance with a CommandsCallbackUrl property, and optionally a CommandsCallbackMethod property (defaults to POST).

                          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 originated from.
                          SimUniqueName The sending SIM's UniqueName, 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 unique id of the Account that this Command belongs to.
                          CommandMode A string representing which mode the SMS was received as. May be text or binary.
                          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 browsing the Twilio tag on Stack Overflow.