# SMSCommand Resource 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) represented by a Sim resource. **SMS Commands** enable you to exchange 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. {% hint style="info" %} If you'd like to try SMS Commands out straight away, check out our [Get Started](https://docs.korewireless.com/en-us/supersim/get-started/get-started-with-super-sim-sms-commands-and-the-raspberry-pi) guide. Or read on for the full API documentation. {% endhint %} ## SMS Commands to SIM (Mobile Terminated) 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: ``` https://supersim.api.korewireless.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](#status-values) below. The SMS received by your device will always come from the number `000`. There is no publicly addressable phone number for your Super SIM meaning that you cannot send an SMS to it from another device. 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-connected 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) 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](https://docs.korewireless.com/en-us/api/products/supersim/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](#sms-command-resource-status-callbacks). {% hint style="danger" %} 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`. {% endhint %} *** ## Asynchronous resource The SMS Command resource performs [asynchronous operations](https://docs.korewireless.com/en-us/api/products/supersim#asynchronous-resources). 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. *** ## API Authorization Before you can make requests to this resource, you must have a valid bearer token. Review our API [authorization guide](https://docs.korewireless.com/en-us/developers/api-management/auth) to learn how to generate a token. Here's a curl example on how to define your access token in a header: {% code overflow="wrap" %} ```bash curl -L "https://supersim.api.korewireless.com/v1/Sims" -H "Authorization: Bearer " ``` {% endcode %} {% hint style="warning" %} The examples below do not show the required `Authorization` header due to a bug. We're working on fixing that. In the meantime, be sure to include that in all of your requests. {% endhint %} *** ## Create an SmsCommand Resource ## POST /v1/SmsCommands > Send SMS Command to a Sim. ```json {"openapi":"3.0.1","info":{"title":"KORE - Supersim","version":"1.0.0"},"tags":[{"name":"SupersimV1SmsCommand"}],"servers":[{"url":"https://supersim.api.korewireless.com"}],"security":[{"OAuth":[]}],"components":{"securitySchemes":{"OAuth":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.korewireless.com/api-services/v1/auth/token","scopes":{}}}}},"schemas":{"supersim.v1.sms_command":{"type":"object","properties":{"sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^HC[0-9a-fA-F]{32}$","nullable":true,"description":"The unique string that we created to identify the SMS Command resource."},"account_sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^AC[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the [Account](https://docs.korewireless.com/en-us/v/api/global-resources/iam/account) that created the SMS Command resource."},"sim_sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^HS[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the [SIM](https://docs.korewireless.com/en-us/v/api/products/supersim/sim-resource) that this SMS Command was sent to or from."},"payload":{"type":"string","nullable":true,"description":"The message body of the SMS Command sent to or from the SIM. For text mode messages, this can be up to 160 characters."},"status":{"$ref":"#/components/schemas/sms_command_enum_status"},"direction":{"$ref":"#/components/schemas/sms_command_enum_direction"},"date_created":{"type":"string","format":"date-time","nullable":true,"description":"The date and time in GMT when the resource was created specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format."},"date_updated":{"type":"string","format":"date-time","nullable":true,"description":"The date and time in GMT when the resource was last updated specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format."},"url":{"type":"string","format":"uri","nullable":true,"description":"The absolute URL of the SMS Command resource."}}},"sms_command_enum_status":{"type":"string","nullable":true,"description":"The status of the SMS Command. Can be: `queued`, `sent`, `delivered`, `received` or `failed`. See the [SMS Command Status Values](https://docs.korewireless.com/en-us/v/api/products/supersim/smscommand-resource#status-values) for a description of each.","enum":["queued","sent","delivered","received","failed"]},"sms_command_enum_direction":{"type":"string","nullable":true,"description":"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`.","enum":["to_sim","from_sim"]}}},"paths":{"/v1/SmsCommands":{"post":{"description":"Send SMS Command to a Sim.","tags":["SupersimV1SmsCommand"],"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/supersim.v1.sms_command"}}},"headers":{"Access-Control-Allow-Origin":{"description":"Specify the origin(s) allowed to access the resource","schema":{"type":"string"}},"Access-Control-Allow-Methods":{"description":"Specify the HTTP methods allowed when accessing the resource","schema":{"type":"string"}},"Access-Control-Allow-Headers":{"description":"Specify the headers allowed when accessing the resource","schema":{"type":"string"}},"Access-Control-Allow-Credentials":{"description":"Indicates whether the browser should include credentials","schema":{"type":"boolean"}},"Access-Control-Expose-Headers":{"description":"Headers exposed to the client","schema":{"type":"string"}}},"description":"Created"}},"operationId":"CreateSmsCommand","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","title":"CreateSmsCommandRequest","properties":{"Sim":{"type":"string","description":"The `sid` or `unique_name` of the [SIM](https://docs.korewireless.com/en-us/v/api/products/supersim/sim-resource) to send the SMS Command to."},"Payload":{"type":"string","description":"The message body of the SMS Command."},"CallbackMethod":{"type":"string","format":"http-method","enum":["GET","POST"],"description":"The HTTP method we should use to call `callback_url`. Can be: `GET` or `POST` and the default is POST."},"CallbackUrl":{"type":"string","format":"uri","description":"The URL we should call using the `callback_method` after we have sent the command."}},"required":["Sim","Payload"]}}}}}}}} ``` *** ## Fetch an SmsCommand Resource ## GET /v1/SmsCommands/{Sid} > Fetch SMS Command instance from your account. ```json {"openapi":"3.0.1","info":{"title":"KORE - Supersim","version":"1.0.0"},"tags":[{"name":"SupersimV1SmsCommand"}],"servers":[{"url":"https://supersim.api.korewireless.com"}],"security":[{"OAuth":[]}],"components":{"securitySchemes":{"OAuth":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.korewireless.com/api-services/v1/auth/token","scopes":{}}}}},"schemas":{"supersim.v1.sms_command":{"type":"object","properties":{"sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^HC[0-9a-fA-F]{32}$","nullable":true,"description":"The unique string that we created to identify the SMS Command resource."},"account_sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^AC[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the [Account](https://docs.korewireless.com/en-us/v/api/global-resources/iam/account) that created the SMS Command resource."},"sim_sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^HS[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the [SIM](https://docs.korewireless.com/en-us/v/api/products/supersim/sim-resource) that this SMS Command was sent to or from."},"payload":{"type":"string","nullable":true,"description":"The message body of the SMS Command sent to or from the SIM. For text mode messages, this can be up to 160 characters."},"status":{"$ref":"#/components/schemas/sms_command_enum_status"},"direction":{"$ref":"#/components/schemas/sms_command_enum_direction"},"date_created":{"type":"string","format":"date-time","nullable":true,"description":"The date and time in GMT when the resource was created specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format."},"date_updated":{"type":"string","format":"date-time","nullable":true,"description":"The date and time in GMT when the resource was last updated specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format."},"url":{"type":"string","format":"uri","nullable":true,"description":"The absolute URL of the SMS Command resource."}}},"sms_command_enum_status":{"type":"string","nullable":true,"description":"The status of the SMS Command. Can be: `queued`, `sent`, `delivered`, `received` or `failed`. See the [SMS Command Status Values](https://docs.korewireless.com/en-us/v/api/products/supersim/smscommand-resource#status-values) for a description of each.","enum":["queued","sent","delivered","received","failed"]},"sms_command_enum_direction":{"type":"string","nullable":true,"description":"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`.","enum":["to_sim","from_sim"]}}},"paths":{"/v1/SmsCommands/{Sid}":{"get":{"description":"Fetch SMS Command instance from your account.","tags":["SupersimV1SmsCommand"],"parameters":[{"name":"Sid","in":"path","description":"The SID of the SMS Command resource to fetch.","schema":{"type":"string","minLength":34,"maxLength":34,"pattern":"^HC[0-9a-fA-F]{32}$"},"required":true}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/supersim.v1.sms_command"}}},"headers":{"Access-Control-Allow-Origin":{"description":"Specify the origin(s) allowed to access the resource","schema":{"type":"string"}},"Access-Control-Allow-Methods":{"description":"Specify the HTTP methods allowed when accessing the resource","schema":{"type":"string"}},"Access-Control-Allow-Headers":{"description":"Specify the headers allowed when accessing the resource","schema":{"type":"string"}},"Access-Control-Allow-Credentials":{"description":"Indicates whether the browser should include credentials","schema":{"type":"boolean"}},"Access-Control-Expose-Headers":{"description":"Headers exposed to the client","schema":{"type":"string"}}},"description":"OK"}},"operationId":"FetchSmsCommand"}}}} ``` *** ## Read multiple SmsCommand Resources ## GET /v1/SmsCommands > Retrieve a list of SMS Commands from your account. ```json {"openapi":"3.0.1","info":{"title":"KORE - Supersim","version":"1.0.0"},"tags":[{"name":"SupersimV1SmsCommand"}],"servers":[{"url":"https://supersim.api.korewireless.com"}],"security":[{"OAuth":[]}],"components":{"securitySchemes":{"OAuth":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.korewireless.com/api-services/v1/auth/token","scopes":{}}}}},"schemas":{"sms_command_enum_status":{"type":"string","nullable":true,"description":"The status of the SMS Command. Can be: `queued`, `sent`, `delivered`, `received` or `failed`. See the [SMS Command Status Values](https://docs.korewireless.com/en-us/v/api/products/supersim/smscommand-resource#status-values) for a description of each.","enum":["queued","sent","delivered","received","failed"]},"sms_command_enum_direction":{"type":"string","nullable":true,"description":"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`.","enum":["to_sim","from_sim"]},"supersim.v1.sms_command":{"type":"object","properties":{"sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^HC[0-9a-fA-F]{32}$","nullable":true,"description":"The unique string that we created to identify the SMS Command resource."},"account_sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^AC[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the [Account](https://docs.korewireless.com/en-us/v/api/global-resources/iam/account) that created the SMS Command resource."},"sim_sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^HS[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the [SIM](https://docs.korewireless.com/en-us/v/api/products/supersim/sim-resource) that this SMS Command was sent to or from."},"payload":{"type":"string","nullable":true,"description":"The message body of the SMS Command sent to or from the SIM. For text mode messages, this can be up to 160 characters."},"status":{"$ref":"#/components/schemas/sms_command_enum_status"},"direction":{"$ref":"#/components/schemas/sms_command_enum_direction"},"date_created":{"type":"string","format":"date-time","nullable":true,"description":"The date and time in GMT when the resource was created specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format."},"date_updated":{"type":"string","format":"date-time","nullable":true,"description":"The date and time in GMT when the resource was last updated specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format."},"url":{"type":"string","format":"uri","nullable":true,"description":"The absolute URL of the SMS Command resource."}}}}},"paths":{"/v1/SmsCommands":{"get":{"description":"Retrieve a list of SMS Commands from your account.","tags":["SupersimV1SmsCommand"],"parameters":[{"name":"Sim","in":"query","description":"The SID or unique name of the Sim resource that SMS Command was sent to or from.","schema":{"type":"string"}},{"name":"Status","in":"query","description":"The status of the SMS Command. Can be: `queued`, `sent`, `delivered`, `received` or `failed`. See the [SMS Command Status Values](https://docs.korewireless.com/en-us/v/api/products/supersim/smscommand-resource#status-values) for a description of each.","schema":{"$ref":"#/components/schemas/sms_command_enum_status"}},{"name":"Direction","in":"query","description":"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`.","schema":{"$ref":"#/components/schemas/sms_command_enum_direction"}},{"name":"PageSize","in":"query","description":"How many resources to return in each list page. The default is 50, and the maximum is 1000.","schema":{"type":"integer","minimum":1,"maximum":1000}},{"name":"Page","in":"query","description":"The page index. This value is simply for client state.","schema":{"type":"integer","minimum":0}},{"name":"PageToken","in":"query","description":"The page token. This is provided by the API.","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"sms_commands":{"type":"array","items":{"$ref":"#/components/schemas/supersim.v1.sms_command"}},"meta":{"properties":{"first_page_url":{"format":"uri","type":"string"},"key":{"type":"string"},"next_page_url":{"format":"uri","nullable":true,"type":"string"},"page":{"type":"integer"},"page_size":{"type":"integer"},"previous_page_url":{"format":"uri","nullable":true,"type":"string"},"url":{"format":"uri","type":"string"}},"type":"object"}},"title":"ListSmsCommandResponse"}}},"headers":{"Access-Control-Allow-Origin":{"description":"Specify the origin(s) allowed to access the resource","schema":{"type":"string"}},"Access-Control-Allow-Methods":{"description":"Specify the HTTP methods allowed when accessing the resource","schema":{"type":"string"}},"Access-Control-Allow-Headers":{"description":"Specify the headers allowed when accessing the resource","schema":{"type":"string"}},"Access-Control-Allow-Credentials":{"description":"Indicates whether the browser should include credentials","schema":{"type":"boolean"}},"Access-Control-Expose-Headers":{"description":"Headers exposed to the client","schema":{"type":"string"}}},"description":"OK"}},"operationId":"ListSmsCommand"}}}} ``` *** ## Status Values 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 KORE 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. | `queued` | The SMS Command is queued in our network waiting to be sent. | | ----------- | ---------------------------------------------------------------------------------------------------- | | `sent` | The SMS Command has been sent to the SIM. | | `delivered` | The SMS Command has been delivered to the SIM and there was a delivery confirmation from the device. | | `received` | The SMS Command has been received from the SIM. | | `failed` | The SMS Command could not be sent. | ## SMS Command resource status callbacks 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 should look similar to the following using `curl`: {% tabs %} {% tab title="Request" %} {% code overflow="wrap" %} ```bash curl -L -X POST "https://supersim.api.korewireless.com/v1/SmsCommands" \ --header "Authorization: Bearer " \ --data-urlencode "Payload={\"enable\":\"True\", \"reset\":\"False\",\"when\":\"Immediate\"}" \ --data-urlencode "Sim=HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \ --data-urlencode "CallbackUrl=" \ --data-urlencode "CallbackMethod=GET" ``` {% endcode %} {% endtab %} {% tab title="Response" %} 
{
"account_sid":"ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"sid":"HCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"payload":"{\"enable\":\"True\", \"reset\":\"False\",\"when\":\"Immediate\"}",
"sim_sid":"HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"direction":"to_sim",
"status":"queued",
"date_created":"2024-10-24T20:12:17Z",
"date_updated":"2024-10-24T20:12:17Z",
"url":"https://supersim.api.korewireless.com/v1/SmsCommands/HCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
{% endtab %} {% tab title="Calback" %} 
Status sent
ApiVersion v1
Payload {"enable":"True", "reset":"False","when":"Immediate"}
SimUniqueName Parking-Meter-Lot-Area-001
SimSid HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
CommandSid HCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Direction to_sim
AccountSid ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
PayloadType text
{% endtab %} {% endtabs %} The request sent to the callback URL contains the following properties:
PropertyDescription
AccountSidThe SID of the Account that the SMS Command resource belongs to. For example: ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
See: What are SIDs and their prefixes?
CommandSidThe unique string that we created to identify the SMS Command resource. For example: HCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
SimSidThe receiving Super SIM's SID. For example: HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
SimUniqueNameThe receiving Super SIM's UniqueName. For example:
Parking-Meter-Lot-Area-001
PayloadThe body of the SMS Command message. This value can be up to 160 characters of text. Binary mode is not supported. For example:
{"enable":"True", "reset":"False","When":"Immediate"}
PayloadTypetext mode by default. 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.
See: Status Values
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.
## Retention Period 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.