You can send an SMS to any of your devices using a POST request to our API. Access our API docs for more information. To learn how, follow the steps below:
The ID of the SIM in your device
An API key or Authorization token
The text that you need to send
How to Find the ID for the SIM in your Device
You are looking for a nine digit number. There are a couple of ways to find it, depending on the type of SIM.
The first, is on SIM card or chip itself. The number is split up into three rows of three. On the card it is easier to read and most can read it without any aids. On the chip the SIM's ID on the chip is much smaller and requires the use of a magnifier to read it. If the SIM is already attached to the device's board, don't worry, since the ID is found on the top of the chip, so it will be visible.
If you are going by the ICCID instead, the SIM ID are the digits from 11-19 or typically also the last 9 digits.
Depending on your set up, another option may be using information found the Onomondo app. However, this requires that you set up an 'alias' name as the label for each SIM you are using.
Obtaining an API key or Authorization token
There are two ways you can authorize your POST request to our API. An API key is a more permanent solution, however, you can also use your browser to find an Authorization token that will allow you to use the API for the remaining of a session. We have a quick guide that can help you:
The text that you need to send to your device
No matter your preferred method of sending POST requests you will need three elements.
In the header
Authorization: API key/token
Content-Type: Application/JSON (Note: This doesn't change)
In the body
The JSON payload with the two keys
from: string
text: your-text-command
The "from" parameter
It is not that important, but required as part of the SMS format and needs to be formatted correctly based on SMS standards. Depending on which format (number or string) you are using you need to make sure meet these requirements.
A number
The number must be a maximum of 15 digits.
Use two zeros, not "+" to declare country code of the number
A string
Length is a maximum of 10 characters
Can be a combination of numbers and characters
Cannot use Symbol characters or spaces (it will return an error)
Otherwise, the "from" parameter is only important if your device has logic to validate where the SMS is coming from. If this is the case, you need to use the phone number or text that the device is expecting for the SMS to work.
The "from" field is required but irrelevant in most cases.
When is it relevant? If there is any logic on the device that checks the from field for validity or security reasons. Then the "from" field needs to comply with logic on the device.
Will my SMS be sent to the location in the 'from' field? No, as normal SMS is insecure and can transmit data and binary directly to your devices. SMS has been designed to only be available through our Network. So the SMS only goes to an open SMS terminal or a Webhook set up for SMS responses.
The "text" parameter
SMS accepts plain text. Make sure you have the right information in the text field. You can normally find what is required in your device's manual.
Just like data traffic, SMS is not stored due to the sensitive information that is often contained in IoT SMS communication - including passwords, device config commands, etc.
An example
Using cURL and an example command I found "APN,onomondo#" to change the APN in an unknown type of modem to "onomondo".
curl --request POST \
--url https://api.onomondo.com/sms/000001000 \
--header 'Authorization: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data '{ "from": "sender", "text": "APN,onomondo#" }'
Once this has been sent, if the sms was sent you will receive a response from the API:
{"message": "OK"}This does not mean that the SMS was received by the device, due to the nature of an SMS. If your device sends something in response that you need to receive, you will need to be on the page of SIM in the App or have set up a SMS Webhook (not SMS usage) on the account:
Just be aware, that the Webhook also sends other events, including usage records and network registration/de-registration. At scale, the events occur quite often, and can cause problems if you haven't setup a proper server to receive them.
Using a Service to send an SMS
If you'd prefer, there are platforms out there that can help you send these requests with less effort. One example is Postman. It let's you set up a Freeimum account, which will cover a reasonable of API requests per month, which often is sufficient during testing.
Once you have downloaded the program, create a request by following the same steps as described above.
Set the request type to 'POST' and add the API url and SIM ID.
Click the 'Headers' tab and add the two required headers.
In the 'Body' tab select raw option, set the formatting to 'JSON' and add the data, same as before and click send. You should receive an 'OK' response if the sms successfully sent.
If you have any further questions, you are welcome to write us on [email protected].