Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

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

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

accountSid
sid<AC> Not PII

The SID of the Account that created the Command resource.

simSid
sid<DE> Not PII

The SID of the Sim resource that the 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

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

transport
enum:transport Not PII

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

deliveryReceiptRequested
boolean Not PII

Whether to request a delivery receipt.

status
enum:status Not PII

The status of the Command. Can 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. 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.

dateCreated
date_time<iso8601> Not PII

The date and time in GMT when the resource was created specified in ISO 8601 format.

dateUpdated
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 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

              The sid or unique_name of the Sim resources to read.

              status
              Optional
              get enum:status Not PII

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

              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. Can be: sms or ip.

              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. Can be plain text in text mode or a Base64 encoded byte string in binary mode.

              sim
              Optional
              post string Not PII

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

              callbackMethod
              Optional
              post http_method Not PII

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

              callbackUrl
              Optional
              post url Not PII

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

              commandMode
              Optional
              post enum:command_mode Not PII

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

              includeSid
              Optional
              post string Not PII

              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.

              deliveryReceiptRequested
              Optional
              post boolean Not PII

              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.

              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.