Sending Data with SMS & USSD

SMS API Service Code (effective 2019-09-10)

SMS sent from the Soracom API to a device (MT SMS) will now originate from service code 901001 instead of service code 900030. This change will provide support for devices that are programmed to automatically send an SMS reply to the originating number. As replies will be returned to 901001, the response can be captured using Unified Endpoint, and further handled with Soracom Beam, Funnel, Funk, and Harvest.

If your devices require a whitelist of incoming numbers, please ensure that service code 901001 is added to the whitelist in order to ensure SMS delivery.

If you are unable to update a device whitelist, you may temporarily opt-out of this update. Please contact Soracom Support for assistance.

Overview

A number of Soracom Air SIMs include SMS (Short Message Service) and USSD (Unstructured Supplementary Service Data) compatibility, allowing you to send and receive data even if a device is offline, such as to restart a device by sending an SMS, or returning diagnostic amounts of data periodically without establishing a network data session.

Although SMS/USSD sending and receiving is possible without a network data session, your device must still be powered on and inside an area with cellular coverage, and the SIM Status must be set to Active.

Compatibility

The following table outlines Soracom Air SIM SMS and USSD support:

Coverage Type SIM Plan SMS USSD
Global plan01s
plan01s - LDV
Japan plan-D (Data/SMS)
plan-D (Data-only)
plan-K
plan-KM1

Service Codes

By using Soracom Air SIMs, you can also extend SMS/USSD functionality with Soracom Beam and Funnel (to forward SMS/USSD data over HTTPS, MQTTS, TCP, or to cloud services), and also Harvest (to store and visualize data directly on Soracom).

When sending an SMS or USSD, simply specify one of the following service codes where you would normally specify a phone number:

Beam, Funnel, and Harvest will then take the data or body of the message, and forward or store it based on their respective configurations.

In some cases, when sending SMS you may be required to specify additional codes so that the service code is properly recognized. If necessary, you can provide the following:

  • NAI (Nature of Address Indicator) or TON (Type of Number) - 0 (Unknown)
  • NPI (Numbering Plan Indicator) - 9 (Private)

SMS Usage Overview

Just like typical SMS usage on mobile phones, SMS is bi-directional and can be used both to send messages to a device, as well as to send data from a device to another device or data endpoint.

Requirements

With the ubiquity of SMS-capable devices, there is generally no special requirement needed. However, please keep the following in mind:

Limitations

For security, SMS sending and receiving is limited to the following conditions:

*1 - When sending SMS from one Air SIM to another, both Air SIMs must be registered to the same Operator

The fees for sending and receiving SMS are not the same! If you are planning to send data from a device to Soracom Beam, Funnel, or Harvest, using USSD (below) to send the data is much cheaper.

The following sending and receiving conditions are not supported:

  • Sending SMS from an Air SIM to a non-Soracom SIM device (such as a personal smartphone)
  • Receiving SMS from a non-Soracom SIM device (such as a personal smartphone)
  • Receiving SMS on the User Console

Additionally, if your device is not within range to receive an SMS, the SMS message is usually stored on the network for a limited time. However, the exact duration varies by each carrier, so SMS delivery is not guaranteed in all cases.


Sending SMS to a Device

Send SMS to Device

Soracom provides several ways to send SMS to your Air SIM device. The simplest method is with the User Console, however the Soracom API allows programmatic usage for integration with applications, and the Soracom CLI allows quick sending from any terminal.

Updated When sending an SMS to your device, the originating number of the SMS will appear as 901001, which corresponds to the Unified Endpoint service code. If your device is configured to automatically send an SMS reply to the same number, the response SMS can be captured using Unified Endpoint, and then further handled using Soracom Beam, Funnel, Funk, and Harvest.


Sending from the User Console

  1. Login to the User Console. From the Menu, open the SIM Management screen.

  2. From the list of subscribers, click the for the SIM card you want to send an SMS to.

  3. Click the Actions menu, then select Send SMS.

    https://console.soracom.io

    Send SMS

  4. Select the Encoding for the message and enter the SMS content, then click Send SMS.

    Send SMS

Sending from the Soracom API

When sending an SMS to a device using the Soracom API, we can use the sendSms method:

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "body": "Hello world!"
>      }' \
>  https://g.api.soracom.io/v1/subscribers/<IMSI>/send_sms

Or, with the MSISDN (phone number) of our Air SIM, using the sendSmsByMsisdn method:

>  ...
>  https://g.api.soracom.io/v1/subscribers/msisdn/<MSISDN>/send_sms

By default, the body parameter must be a string containing ASCII characters. If needed, we can switch the encoding to hex or multi-byte by adding an encodingType parameter to the body:

{
  "body": "74657374",
  "encodingType": 3
}

Valid values for encodingType are:

  • 1 (or not specified) - ASCII
  • 2 - multi-byte
  • 3 - hexadecimal (binary)

Sending from the Soracom CLI

Using the Soracom CLI is similar to the API:

soracom subscribers send-sms --imsi <IMSI> --payload "Hello world!" --coverage-type g

Or with the device's MSISDN:

soracom subscribers send-sms-by-msisdn --msisdn <MSISDN> --payload "Hello world!" --coverage-type g

To specify the content encoding, simply add a --encoding-type flag:

  • --encoding-type 1 (or not specified) - ASCII
  • --encoding-type 2 - multi-byte
  • --encoding-type 3 - hexadecimal (binary)

Sending SMS from a Device

Send SMS from Device

The method for sending an SMS will vary depending on the type of device. Regardless of the type of device and method for sending SMS, you will need to know the destination address, which must be one of the following:

In addition to the destination address, you may need to manually set the encoding type for your content, so that the content is transmitted correctly. The maximum length of the content may vary depending on the encoding type.


Sending SMS from a Smartphone

To send the value 123 to Harvest, simply launch the messaging app and send a message containin 123 to the service code 901031.


Sending SMS from a 3G/LTE Modem

When interacting with a 3G/LTE modem, you can connect to its serial interface and send SMS using AT commands.

To interact with a 3G/LTE modem, we need to use it inside an AT command, since we are interacting with the modem directly. Connect to the modem using a serial interface.

The serial interface will have a > prompt, indicating that you can issue AT commands to the modem. The AT+CMGF= command will tell configure the modem to use text format, and the AT+CMGS= command will initiate the send SMS message command. Then, the modem will accept input for the SMS content. Once we have input the content, we need to send a control code to signal to the modem that content input is complete. Typically, pressing Ctrl+Z or Esc will complete the send SMS command:

AT+CMGF=1
<OK
<
AT+CMGS="901031"
<>123 <Ctrl+Z or Esc>
<OK

The above command works well for many typical modems, however in some instances, the modem may return CMS ERROR along with an error code. Typical errors occur because the modem is not registered to a network, or there was a problem with the character encoding type. The modem manufacturer's AT command manual will explain the meaning of each error code, allowing you to run additional AT commands to set up the modem to send SMS.

If the error is due to incorrect encoding type, you can use the AT+CSCS= command to change it. In some cases, a modem may default to a different encoding. To send a simple test message, we will set the encoding type to GSM:

AT+CSCS="GSM"
<OK

Then we can run the AT+CMGF= and AT+CMGS= commands above to send an SMS.

Different modem manufacturers may employ different AT commands, and occasionally their syntax may vary slightly. Please refer to your modem's AT command manual for details on preparing the modem for sending SMS, changing the character set, and sending an SMS.


Sending SMS from an Arduino Device

In some cases, libraries are available for certain devices that allow you to send SMS without directly entering AT commands. For example, the Wio LTE microcontroller can be used with the Wio LTE for Arduino library, which includes a command for sending an SMS. All we need to provide is the SMS destination address and message to send:

#include <WioLTEforArduino.h>

WioLTE Wio;

void setup() {
  delay(200);

  Wio.Init();
  Wio.PowerSupplyLTE(true);
  delay(500);

  Wio.TurnOnOrReset();
  delay(3000);

  Wio.SendSMS("901031", "123");
}

void loop() {

}

You can find the full code example, which includes basic error handling, from the Wio LTE for Ardunio library within Arduino IDE Library Manager.


USSD Usage Overview

USSD allows similar functionality as SMS, however messages can only be sent from a device to the network, and must be sent while the device is connected to the network. USSD is best suited when you only need to occasionally upload small amounts of data from your device.

Requirements

Sending USSD requires a device that supports USSD.

To date, Soracom has confirmed that the following devices support USSD and are capable of transferring text data:

If your device is not listed, please check the device manual or contact the device manufacturer to confirm USSD capability.

For testing USSD transmission, you can send data using a typical smartphone dialer.

Appended Data

When USSD is used to send data to Beam or Funnel, the data is cast into a JSON object before it is sent to the destination endpoint, in order to provide additional information about the USSD data.

For example, when we send a USSD message with the following AT command:

AT+CUSD=1,"*901031*123#",15
<OK

Soracom Beam or Funnel will receive the data and send the following JSON payload to our endpoint:

{
  "imsi": "295000012345678",
  "ussdDataCodingScheme": 15,
  "ussdString": "*901011*123#",
  "value": "123"
}

In addition to our value 123, we will receive the imsi which we can use for handling the data on our endpoint, and we will also receive the ussdString which we can use to inspect the message for errors.

Limitations

Currently, USSD can only be used with an Air SIM to send data from a device, and is limited to the following conditions:

Additionally, the transfer speed is relatively slow, so it is not suited for sending large amounts of data.


Sending USSD from a Device

Sending a USSD message is typically done by sending AT commands to a modem, or by dialing a specially-designated number using a device's dialer interface.

Regardless of device, USSD messages use the following format: *{service code}*{data}#, where:


Sending USSD from a Smartphone

To send the value 123 to Harvest (service code 901031), simply launch the dialer and dial the following code:

*901031*123#

Sending USSD from a 3G/LTE Modem

When interacting with a 3G/LTE modem, you can connect to its serial interface and send USSD using AT commands.

Just like the smartphone example, we'll use the USSD message *901031*123#. However, in order to interact with a 3G/LTE modem, we need to use it inside an AT command, since we are interacting with the modem directly. Connect to the modem using a serial interface.

The serial interface will have a > prompt, indicating that you can issue AT commands to the modem. The AT+CUSD= command will send the USSD message:

AT+CUSD=1,"*901031*123#",15
<OK

The above command works for standard modems such as the Quectel UC20 and UC96, however some device manufacturers initialize their modems with different configurations. For the Huawei MS2131i-8 and MS2372h-607, we also need to run AT^USSDMODE and AT+CSCS= to make sure the USSD mode and character set is configured correctly, respectively:

AT^USSDMODE=0
<OK
AT+CSCS="GSM"
<OK
AT+CUSD=1,"*901031*123#",15
<OK

AT^USSDMODE=0 is specific to Huawei USB modems, and configures USSD to send data using 3GPP specifications, and AT+CSCS="GSM" sets the character set to GSM 7-bit default alphabet. These only need to be set once when the modem is powered on. Afterwards, the USSD send command can be repeated to send data multiple times.

Different modem manufacturers may employ different AT commands, and occasionally their syntax may vary slightly. Please refer to your modem's AT command manual for details on setting the USSD mode, character set, and sending USSD.


Sending USSD from an Arduino Device

In some cases, libraries are available for certain devices that allow you to send USSD without directly entering AT commands. For example, the Wio 3G SORACOM Edition microcontroller can be used with the Wio cell lib for Arduino library, which includes a command for sending a USSD. All we need to provide is the USSD message to send:

#include <WioCellLibforArduino.h>

WioCellular Wio;

void setup() {
  delay(200);

  SerialUSB.begin(115200);
  Wio.Init();
  Wio.PowerSupplyCellular(true);
  delay(500);

  Wio.TurnOnOrReset();
  Wio.WaitForCSRegistration();

  const char* message = "*901031*123#"; // USSD message
  char response[256];
  Wio.SendUSSD(message, response, sizeof (response));

  SerialUSB.println(response);
}

void loop() {

}

You can find the full code example, which includes basic error handling, from the Wio cell lib for Ardunio library within Arduino IDE Library Manager.


Usage with Beam, Funnel, and Harvest

When sending SMS or USSD message from your device to Beam, Funnel, or Harvest, you will also need to perform the respective services.

In general, configuration requires:

  1. Creating a Group
  2. Configuring the Group to enable Beam, Funnel, or Harvest, with appropriate settings
  3. Adding your Air SIM to the Group

Once the Group configuration is complete, SMS and USSD messages sent from your device will be sent to the respective service.


Testing

As Harvest will capture data without requiring any configuration, you can use it to quickly perform SMS and USSD connectivity tests. Enable the Harvest service in your Group configuration, then send an SMS or USSD to the 901031 service code.

If the send is successful, the transmitted data will be stored in Harvest. To view the data, open the User Console and select the next to the Air SIM, then click the Actions menu and select Harvest data. The test data will appear in the logs below.