How do I send an SMS to my device using the API?

You can use our API to send an SMS to any or all of your devices.

 

You can send an SMS to any of your devices using a POST request to our API. To do this you need to know:

  1. The id of the SIM in your device
  2. An API key or Authorization token
  3. The text that you need to send

1. Finding the id of 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 magnifying glass or something similar to read it. 

And don't worry if it is already attached to the device's board as the number is found on the top of the chip, so you will be able to see it. 

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 for each SIM you are using.

2. Obtaining an API key or Authorization token.

There a 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:

3. 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:

  1. Authorization:  API key/ token
  2. Content-Type: application/json (Note: This doesn't change)

In the body:

  1. The JSON payload with the two keys
    1. from: string
    2. 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.

1. A number

  • The number must be a maximum of 15 digits. 
  • Use two zeros, not "+" to declare country code of the number

2. 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.

"from" field is required but in most cases irrelevant. 

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 unsecure 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 "body" 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 often sensitive nature contained in IoT SMS communication - including passwords, device config commands, etc.

A quick 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 have not set up 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. Add follow the same steps from above. 

First, Set the request type to 'POST' and add the API url. the nine digits at the end is the SIM id found under the barcode on your sim card, or written on the mff2 chip. If you are going by the ICCID instead, the SIM id is the last 9 digits.

Afterwards, click the 'Headers' tab and add the two required headers. 

Finally, 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 more questions, don't hesitate to reach out at support@onomondo.com.