# SMS Events

> For the complete documentation index, see [llms.txt](https://help.1nce.com/llms.txt).

# SMS Events

The 1NCE Data Streamer Service provides real-time SMS Events that give you detailed insights into SMS traffic for your IoT devices. This chapter focuses on the two types of SMS Events supported by the platform.

## SMS Event Types

**SMS MT DLR** — MT (Mobile Terminated) Delivery Reports provide status updates for SMS messages sent to devices, including delivery confirmations, failures, and expiry notifications.

**SMS MO** — MO (Mobile Originated) events represent SMS messages sent from mobile devices to your specified interfaces or applications.

## Event Specifications

### SMS MT DLR (Delivery Report)

SMS MT Delivery Reports are generated when SMS messages sent to devices reach a final state. These events provide delivery status information including successful delivery, failures, or expiration.

**Supported Status Types:**
- `DELIVERED`: Message successfully delivered to the device
- `FAILED`: Message delivery failed
- `EXPIRED`: Message expired before delivery

<details>
<summary>SMS MT DLR Example</summary>

```json
{
  "id": 8891889,
  "submit_date": "2024-12-15T16:55:31Z",
  "final_date": "2024-12-15T16:55:35Z",
  "organisation": {
    "id": 103820
  },
  "endpoint": {
    "id": 100001494,
    "name": "8988228530100000216"
  },
  "status": {
    "status": "DELIVERED",
    "id": 4
  },
  "detail": {
    "sms": {
      "id": "551734281731175386"
    }
  }
}
```

</details>

### SMS MO (Mobile Originated)

SMS MO events represent messages sent from mobile devices to your customer-specified interfaces. These events capture the complete SMS content and routing information.

<details>
<summary>SMS MO Example</summary>

```json
{
  "id": 8901947,
  "submit_date": "2024-12-16 07:01:00",
  "pid": 0,
  "organisation": {
    "id": 103820
  },
  "dest_address": "338",
  "source_address": "882285301000216",
  "dcs": 0,
  "payload": "34178d09-905a-4289-95b6-da61f966d3e1;1734332456",
  "endpoint": {
    "id": 100001494,
    "name": "8988228530100000216"
  }
}
```

</details>

## SMS Event Properties

### Common Properties

Properties shared across both SMS event types:

| Property       | Data Type             | Description                                                |
| :------------- | :-------------------- | :--------------------------------------------------------- |
| `id`           | LONG (64-bit integer) | Unique identifier for each SMS event                      |
| `submit_date`  | TIMESTAMP (UTC)       | Timestamp when the SMS was submitted in ISO 8601 format   |
| `organisation` | JSON Object           | Organization information containing the organization ID    |
| `endpoint`     | JSON Object           | Endpoint information including ID and name (typically ICCID) |

### SMS MT DLR Properties

Specific properties for MT Delivery Report events:

| Property      | Data Type       | Description                                           |
| :------------ | :-------------- | :---------------------------------------------------- |
| `final_date`  | TIMESTAMP (UTC) | Timestamp when the final delivery status was reached |
| `status`      | JSON Object     | Delivery status information                           |
| `detail`      | JSON Object     | Additional details including original SMS ID          |

**Status Object:**
- `status`: String value (`DELIVERED`, `FAILED`, `EXPIRED`)
- `id`: Numeric status identifier (4 = DELIVERED, 5 = FAILED, 6 = EXPIRED)

### SMS MO Properties

Specific properties for Mobile Originated SMS events:

| Property         | Data Type | Description                                        |
| :--------------- | :-------- | :------------------------------------------------- |
| `dest_address`   | STRING    | Destination address where the SMS was sent        |
| `source_address` | STRING    | Source address (typically the device's MSISDN)    |
| `payload`        | STRING    | The actual SMS message content                     |
| `dcs`            | INTEGER   | Data Coding Scheme (0 = default GSM 7-bit)        |
| `pid`            | INTEGER   | Protocol Identifier (0 = default)                 |

## Object Details

### Organisation Object

Contains information about the customer organization:

| Property | Data Type | Description                     |
| :------- | :-------- | :------------------------------ |
| `id`     | INTEGER   | Unique 1NCE customer organization identifier |

### Endpoint Object

Represents the device/SIM endpoint:

| Property | Data Type | Description                                    |
| :------- | :-------- | :--------------------------------------------- |
| `id`     | INTEGER   | Unique endpoint identifier                     |
| `name`   | STRING    | Endpoint name (typically the ICCID)           |

### Detail Object (SMS MT DLR)

Contains additional information specific to delivery reports:

| Property | Data Type   | Description                          |
| :------- | :---------- | :----------------------------------- |
| `sms`    | JSON Object | Contains the original SMS identifier |

**SMS Detail Object:**
- `id`: Original SMS message identifier for correlation

## Integration Notes

- SMS Events are delivered in real-time through the 1NCE Data Streamer
- Each event includes a unique ID to handle potential retransmissions
- Timestamps are provided in UTC format following ISO 8601 standard
- Status codes are consistent across the platform for reliable processing