# SMS Specification

This section is divided in two parts:

1. Content - what the content of the ELS messages is.
2. Formats - how those messages are sent and how to decode them (if needed).

## Content

### ELS V1

ELS messages sent over SMS follow the latest [ETSI AML specification](https://www.etsi.org/standards#page=1&search=AML&title=1&etsiNumber=1&content=1&version=0&onApproval=1&published=1&withdrawn=1&historical=1&isCurrent=1&superseded=1&startDate=1988-01-15&harmonized=0&keyword=&TB=&stdType=&frequency=&mandate=&collection=&sort=1). This
is known as ELS V1 and it's the most common approach chosen by ELS partners. The
following are the most relevant sections:

| **Key Name** | **Value** | **Units** | **Example** |
|---|---|---|---|
| `A"ML` | Version | - | 1 |
| `lt` | Latitude | degrees | +37.42175 |
| `lg` | Longitude | degrees | -122.08461 |
| `top` | Timestamp of location | yyyyMMddHHmmss in UTC time | 20150613010948 |
| `rd` | Location Accuracy | meters | 20.0 |
| `lc` | Location Confidence | Percentage confidence | 68 |
| `pm` | Positioning Method (Wi-Fi, GPS, Cell, Null) | 'W', 'G', 'C', 'N' | W |
| `si` | IMSI (only contains first 6 digits of original IMSI, remaining digits are replaced with 0) | - | 123456000000000 |
| `ei` | IMEI | - | 355458061005220 |
| `mcc` | Network MCC | - | 310 |
| `mnc` | Network MNC | - | 260 |
| `ml` | Length of message (including message length and header) | - | 123 |

#### Positioning method

> [!CAUTION]
> **Caution:** Because ELS V1 doesn't support an unknown positioning method, in rare cases ELS may return a positioning method (`pm`) of '`N`' if the positioning method is unknown or ELS is unable to determine a location.

#### Null location

> [!CAUTION]
> **Caution:** When ELS is unable to determine a location, per ETSI specification, it will send zero location values: `lt=+00.00000,ln=+000.00000,rd=N,lc=0`. See the following example for full no location behavior.

#### Examples

No location:

    A"ML=1;lt=+00.00000;lg=+000.00000;rd=N;top=20220131173734;lc=0;pm=N;si=234159000000000;ei=123456789012345;mcc=234;mnc=15;ml=127

Location computed:

    A"ML=1;lt=+51.53321;lg=-0.12601;rd=14;top=20220131171748;lc=68;pm=W;si=234159000000000;ei=123456789012345;mcc=234;mnc=15;ml=126

### ELS Beta

An experimental format used by a few partners is ELS Beta, our experimental
content that gives partners the opportunity to try different fields.

> [!WARNING]
> **Warning:** As this is experimental, partners should accept that there may be more regular updates to this format that may require changes to their endpoint.

The following are the most relevant sections:

| **Key Name** | **Value** | **Units** | **Example** |
|---|---|---|---|
| `A"ML` | Version | - | 2 |
| `en` | Emergency Number | - | 911 |
| `et` | Timestamp of emergency call | UNIX epoch time in seconds (integer) | 1593187189 |
| `lo` | Location (latitude, longitude, accuracy) - latitude and longitude must be truncated to 5 decimal points, accuracy to 1 decimal point - an accuracy of 0 represents unknown | Degrees (float), Degrees (float), Meters (float) | 37.42175,-122.08461,20.1 |
| `lt` | Location time (relative to emergency time) - this field may be ignored if no location ('lo') field is present or no timestamp ('et') field is present | Seconds (integer) | 5 |
| `lc` | Location Confidence | Percentage confidence (integer) | 68 |
| `lz` | Vertical Location (altitude, vertical accuracy) - this field may be ignored if no location ('lo') field is present - all fields truncated to 1 decimal point - an accuracy of 0 represents unknown | Meters (float), Meters (float) | -10.1,10.1 |
| `ls` | Location Source (Wi-fi, Cell, GPS, Fused, Unknown) - this field may be ignored if no location ('lo') field is present | 'W', 'G', 'C', 'F', 'U' | W |
| `ei` | IMEI | - | 355458061005220 |
| `nc` | Network MCC/MNC | - | 310260 |
| `hc` | Home MNC/MNC | - | 310260 |
| `lg` | Language Tags | IETF BCP 47 | en-US |

#### Confidence level

> [!NOTE]
> **Note:** The confidence level in the message may be controlled using a configuration option. See the configuration options documentation (Partners-only access) for more information.

### Altitude Elevation (Z-axis)

ELS reports vertical location and accuracy in ELS Beta messages. Altitude `lz`
is reported in meters above the WGS84 reference ellipsoid (WGS is the reference
World Geodetic System used by GPS) and accuracy in meters (altitude, vertical
accuracy). This field may be ignored if no location (`lo`) field is present. All
fields truncated to 1 decimal point and an accuracy of `0.0` represents
`unknown`. Vertical accuracy is defined the same as location accuracy and the
confidence percentile is set by the partner. The default is set at 68%
confidence. More information is available in the Android documentation for
[getVerticalAccuracyMeters()](ftp://www.3gpp.org/tsg_t/TSG_T/TSGT_04/Docs/PDFs/TP-99127.pdf).

#### Examples

Location not yet computed case:

    A"ML=2;en=911;et=1643816841;ei=123456789012345;nc=23415;hc=23415

Location successfully computed case:

    A"ML=2;en=911;et=1643816929;lo=51.53321,-0.12601,14.7;lt=6;lc=68;lz=77.6,1.0;ls=W;ei=123456789012345;nc=23415;hc=23415

## Formats

ELS messages over SMS can be sent using the following formats:

- **Text SMS**: Regular plain SMS. This format is supported starting from Android P.
- **Data SMS**: The content of the message is exactly the same as Text SMS but it is encoded (more details below). This format is supported by any Android-powered device compatible with ELS.

### Text SMS

Reading and parsing Text SMS is relatively straight forward. Many mobile
operators offer this service and can provide you with push or pull APIs to get
the content of messages sent to a standard phone number.

> [!NOTE]
> **Note:** We often refer to Text SMS as 'Hybrid SMS'. This is because when enabling Text SMS as a method of sending ELS messages, the system will switch to Data SMS for devices older than Android P.

### Data SMS

Regular Text SMS format has been supported starting from Android P. Older
devices will send ELS messages using Data SMS that need to be decoded. ELS Data
SMS messages are encoded with the GSM 03.38 7 bit default character set and then
set as the binary payload of a Data SMS.

The exact definition of a Data SMS as opposed to a normal SMS is covered later.
The exact definition of the GSM 03.38 7 bit encoding can be found in [3GPP
23.038](ftp://www.3gpp.org/tsg_t/TSG_T/TSGT_04/Docs/PDFs/TP-99127.pdf) (see section 6.1.2.1.1 specifically).

> [!CAUTION]
> **Caution:** Some telephony providers may need changes to reliably transmit Data SMS messages; they differ substantially enough from 'plain text' SMS messages as to sometimes require additional configuration and monitoring.

#### Decode Data SMS

For the purposes of Google's usage of SMS for ELS, ELS is only concerned with
SMS from the handset to the mobile service center (SMSC) - SMS-SUBMIT type
messages. SMSCs should be able to receive these messages without problems as
they are part of the normal SMS standard (however, in practice we have observed
problems with several MNOs, ranging from infrastructure settings and policies to
difficulty properly decoding Data SMS). In the following, ELS considers an
SMS-SUBMIT message from the handset to the SMSC, which follows normal SMS
standards (GSM 3.40). ELS defines a Data SMS as a subset of normal SMS that:

1. Has the User-Data-Header-Indicator flag set in the SMS header (6th bit of the first octet of a GSM 03.40 or 3GPP 23.040 message)
2. Contains a User-Data-Header within the User-Data of the SMS
3. The User-Data-Header contains an application port address Information-Element-Identifier (IEI)

It is necessary for ELS to send an SMS in this fashion rather than a regular SMS
to ensure that ELS Data SMS messages don't appear in the Android device's
messaging app. An example encoded SMS is presented later to better explain this.

Note that we don't specify a particular Data-Coding-Scheme (DCS) here. The DCS
is used to identify the encoding within the User-Data segment. However, for the
foreseeable future, the Data-Coding-Scheme will always be set to 8 bit data to
allow for maximum flexibility, and the actual data itself will be encoded with
the GSM 03.38 7 bit default alphabet. Each 7 bit encoded element will thus
occupy only 7 bits, not 8 bits.

Given that the User-Data segment has a maximum of 140 bytes, and that the
minimum size of a User-Data-Header that includes port information is 7 bytes,
this leaves a maximum of 133 bytes (152 7 bit encoded elements) to encode the
actual emergency message. These bytes may be decoded to reveal the ELS Data SMS
message being transmitted.

> [!CAUTION]
> **Caution:** many SMS communications providers (companies such as Twilio, Nexmo, etc...) may need additional configuration to decode this raw binary data as they often assume UTF8 encoding. If such a provider is used, it may be necessary to communicate that you need access to the raw binary data.

##### Example

Thus, after decoding this example Data SMS, we're left with the binary user Data
of this hex string:

`415193D98BEDD8F4DEECE6A2C962B7DA8E7DEEB56232990B86A3D9623B39B92783EDE86F784F068BD560B6D80C1683E568B81D7BDCB3E176F076EFB89BA77B39DCCD56A3C966B15D39DD9BD570B2590E56CBC168B21A4DB66B8FC7BD590CB66BBBC73D990DB66BB37B31D94CC12CBBCF74B40E1493CD1A`

#### Decode GSM 03.38

The following example decodes the first couple octets, the rest is left as an
exercise to the reader. We suggest referencing 3GPP 23.038 and using many of the
helpful online tools (for example,
<http://smstools3.kekekasvi.com/topic.php?id=288>). Within the Octets column,
the yellow highlighted sections represent the bits that are not used for the
current septet, and are left over for the next septet. Within the Septets
column, the yellow highlighted sections represent the bits from the previous
octet.

| **Hex** | **Octets** | **Septets** | **Character (Hex)** |
|---|---|---|---|
| `41` | `01000001` | `1000001` | `A (41)` |
| `51` | `01010001` | `0100010` | `" (22)` |
| `93` | `10010011` | `1001101` | `M (4D)` |
| `D9` | `11011001` | `1001100` | `L (4C)` |
| `8B` | `10001011` | `0111101` | `= (3D)` |
| `ED` | `11101101` | `0110001` | `1 (31)` |
| `D8` | `11011000` | `0111011` | `; (3B)` |
|   |   | `1101100` | `l (6C)` |
| `F4` | `11110100` | `1110100` | `t (74)` |
| `DE` | `11011110` | `0111101` | `= (3D)` |

The end result here is that the previous message may be decoded into the
following string:

`A"ML=1;lt=37.42175;lg=-122.08461;rd=20;top=20150613010948;lc=68;pm=G;si=987654231;ei=358239059042542;mcc=310;mnc=260;ml=123`

These SMS should be able to be decoded with most publicly available SMS
software.