Command Resource
The Command resource enables you to exchange 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 KORE'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
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.
Retention period
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.
Command Properties
sid SID<DC>
The unique string that we created to identify the Command resource.
Pattern:^DC[0-9a-fA-F]{32}$
Min length:34
Max length:34
account_sid SID<AC>
The SID of the Account that created the Command resource.
Pattern:^AC[0-9a-fA-F]{32}$
Min length:34
Max length:34
sim_sid SID<DE>
The SID of the Sim resource that the Command was sent to or from.
Pattern:^DE[0-9a-fA-F]{32}$
Min length:34
Max length:34
command string 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_mode enum<string>
The mode used to send the SMS message. Can be: text or binary. The default SMS mode is text.
Possible values:
text
binary
transport enum<string>
The type of transport used. Can be: sms or ip.
Possible values:
sms
ip
delivery_receipt_requested boolean
Whether to request a delivery receipt.
status enum<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:
queued
sent
delivered
received
failed
direction enum<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_sim
to_sim
date_created string<date-time>
The date and time in GMT when the resource was created specified in ISO 8601 format.
date_updated string<date-time>
The date and time in GMT when the resource was last updated specified in ISO 8601 format.
url string<uri>
The absolute URL of the resource.
Status values
queued
The Command is queued in our 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 only.
received
The Command has been received from the SIM. For from_sim Commands only.
failed
The Command has failed to be transmitted.
Create a Command resource
Creating a Command resource sends the command to the SIM.
Callback values
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.
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.
Send a Command to a Sim
Fetch a Command resource
Read multiple Command resources
The maximum PageSize you can request when reading Commands is 100.
Delete a Command resource
Receive a Command from a SIM
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.
CommandSid
The SID of this Command.
SimSid
The SIM this Command was sent by.
SimUniqueName
The sending SIM's friendly name, 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 SID of the Account that this Command belongs to.
CommandMode
A string representing which mode the SMS was received as. May be text or binary.
Last updated