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

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 subscriber status must be set to Active.

Compatibility

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

Coverage Type SIM Type SMS USSD
Global plan01s
plan01s - LDV
plan-NA1
planP1 MT-SMS only *1
planX1
planX2
Japan plan-D (Data/SMS)
plan-D (Data-only)
plan-DU
plan-K
plan-KM1

*1 - Mobile Terminated SMS, or SMS delivered from Soracom to a device

Service Codes

By using Soracom Air SIMs, you can also extend SMS/USSD functionality with Soracom Beam, Funnel, and Funk (to forward SMS/USSD data over HTTPS, MQTTS, TCP, or to cloud services), and also Harvest Data (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, Funk, and Harvest Data 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)

Be careful not to prepend the service code with a + symbol. If the number begins with a + symbol, it will be recognized as a phone number rather than a service code, and will result in an error.

Configuration

When sending SMS or USSD message from your device to Beam, Funnel, Funk, Harvest Data, or any of the above with Unified Endpoint, you must also configure the following:

  1. Create a Group
  2. Configure the Group to enable Beam, Funnel, Funk, or Harvest Data, with appropriate settings
  3. Add 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.


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, Funk, or Harvest Data, using USSD (below) to send the data is much cheaper. Please refer to the Pricing & Fee Schedule documentation for information on SMS charges.

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)

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

Sending an SMS to your device will incur an MT SMS fee. Refer to the Pricing & Fee Schedule for more information.

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

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

From the Soracom API

To access the Soracom API, first use the auth API to obtain an API Key and Token. Refer to the API Reference Guide for instructions on how to use the API Key and Token in API requests.

Then, use the sendSms API to send an SMS to an Air SIM using its IMSI:

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

Then, use the sendSmsByMsisdn API to send an SMS to an Air SIM using its MSISDN:

curl -X POST \
>  ...
>  https://g.api.soracom.io/v1/subscribers/msisdn/<MSISDN>/send_sms

By default, the payload parameter must be a string, and Soracom will send the SMS using multi-byte (UCS-2) encoding. Because of this, the SMS message will be limited to 70 characters. If needed, you can specify the encoding to ASCII (GSM-7) or hexadecimal (binary) by adding an encodingType parameter to the body:

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

Valid values for encodingType are:

  • 1 - ASCII (GSM-7)
  • 2 (default if not specified) - multi-byte (UCS-2)
  • 3 - hexadecimal (binary)

From the Soracom CLI

To use the Soracom CLI, you must first configure it to authenticate with your account information, authorization key, or SAM user credentials.

Then, run the following command to send an SMS to an Air SIM using its IMSI:

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

Or using the Air SIM'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 - ASCII (GSM-7)
  • --encoding-type 2 (default if not specified) - multi-byte (UCS-2)
  • --encoding-type 3 - hexadecimal (binary)

Sending SMS from a Device

Sending an SMS from your device will incur an MO SMS fee. Refer to the Pricing & Fee Schedule for more information.

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.

Soracom does not support processing SMS User Data fields that include a header. If a header is included, the User Data field will be processed as-is and will result in unwanted or malformed text content, and may further cause unwanted behavior with Beam, Funnel, Funk, Harvest Data, or other applications. When configuring a device to send data to Soracom, ensure that the User Data Header Indicator (UDHI) or corresponding SMS header option is disabled.


From a Smartphone

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


From a Modem using AT Commands

When interacting directly with a modem, you can connect to the modem's serial interface and send AT commands to send an SMS.

Once connected, we can send the following AT commands:

The above commands works well for many typical modems, however in some instances, the modem may return CMS ERROR along with an error code. The modem manufacturer's AT command manual will usually explain the meaning of each error code.

If an error is due to using an incorrect encoding type, you can use the AT+CSCS= command to change it:

AT+CSCS="GSM"
<OK

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

Different modem manufacturers may have additional AT commands related to SMS. Refer to your modem's AT command manual for details on configuring the modem, changing the character set, and sending SMS.


From an Arduino Device

GSM libraries are usually available for several kinds of devices and 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.

Soracom has tested and confirmed a number of devices that support USSD, including:

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 also send a USSD message from a smartphone using its 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 from your device will incur a USSD request fee. Refer to the Pricing & Fee Schedule for more information.

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:


From a Smartphone

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

*901031*123#

From a Modem using AT Commands

When interacting directly with a modem, you can connect to the modem's serial interface and send AT commands to send a USSD message.

Once connected, we can send the following AT commands:

This 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. 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 have additional AT commands related to USSD. Refer to your modem's AT command manual for details on configuring the modem, changing the character set, and sending USSD.


From an Arduino Device

GSM libraries are usually available for several kinds of devices and 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.


Testing

Since the Harvest Data service captures data without requiring any configuration, you can use it to quickly perform SMS and USSD connectivity tests. Enable the Harvest Data 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 Data. 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.