# Custom SMS events

Airship delivers SMS messages through service providers Sinch (formerly known as CLX) and Twilio. Custom SMS events represent events that occur between the service provider and recipient. They do not represent Airship service events.


## RCS read report {#rcs-read-report}

Read reports are Custom Events sent when an RCS message is marked as read. These events use the `delivery_report` interaction type with a `name` of `read`. See [RCS branded senders](/docs/developer/api-integrations/sms/rcs/).


- **`body`** `object` **REQUIRED**
  **OBJECT PROPERTIES**

  - **`interaction_type`** `string`

    Possible values: `delivery_report`

  - **`name`** `string` **REQUIRED**

    Indicates the event is an RCS read.

    Possible values: `read`

  - **`properties`** `object` **REQUIRED**
    **OBJECT PROPERTIES**

    - **`is_rcs`** `boolean`

      A boolean describing whether the message was delivered as RCS.

    - **`number_of_message_parts`** `number`

      The number of message parts delivered.

    - **`recipient_country_code`** `string`

      The country code of the message recipient.

    - **`sender`** `string` **REQUIRED**

      The number or short code that the message originated from.

    - **`vendor`** `string` **REQUIRED**

      The delivery service for the message.

      Possible values: `CLX`, `TWILIO`

    - **`vendorDeliveryId`** `string` **REQUIRED**

      A unique identifier for the message from the SMS vendor.

  - **`source`** `string` **REQUIRED**

    Possible values: `API`

  - **`triggering_push`** `object`

    Identifies the push notification that caused the event.

    **OBJECT PROPERTIES**

    - **`campaigns`** `object`

      An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit.

      **OBJECT PROPERTIES**

      - **`categories`** `array[string]`
    - **`group_id`** `string`

      Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification.


      Format: `uuid`

    - **`push_id`** `string` **REQUIRED**

      A unique identifier for a push operation.

      Format: `uuid`

- **`device`** `object` **REQUIRED**

  Device properties for Custom Events with the `delivery_report` interaction type always specify an SMS device.

  **OBJECT PROPERTIES**

  - **`channel`** `string` **REQUIRED**

    The unique, platform-agnostic channel identifier for a device.

  - **`delivery_address`** `string` **REQUIRED**

    The phone number associated with the channel.

  - **`device_type`** `string` **REQUIRED**

    Possible values: `SMS`

- **`id`** `string` **REQUIRED**

  Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate.

- **`occurred`** `string` **REQUIRED**

  When the event occurred.

- **`offset`** `string` **REQUIRED**

  An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason.

- **`processed`** `string` **REQUIRED**

  When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed.

- **`type`** `string` **REQUIRED**

  Possible values: `CUSTOM`


**Used in:**

- [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream)

---

## SMS delivery report {#delivery-report}

Delivery reports are Custom Events sent from our third-party SMS providers.
These events report the status of your message between the provider and your audience up to, and including, delivery.


[Jump to examples ↓](#delivery-report-examples)

- **`body`** `object` **REQUIRED**
  **OBJECT PROPERTIES**

  - **`interaction_type`** `string`

    Possible values: `delivery_report`

  - **`name`** `string` **REQUIRED**

    The name of the delivery report as specified by the vendor. Most events reference the status of the message with reference to the short message service center (SMSC) — the server that receives your message and dispatches it to your audience.

* dispatched — Message has been dispatched and accepted for delivery by the SMSC.
* aborted — Message was aborted before reaching SMSC.
* rejected — Message was rejected by SMSC.
* delivered — Message has been delivered.
* failed — Message failed to be delivered.
* expired — Message expired before delivery to SMSC. This may happen if the expiry time for the message was very short.
* unknown — Message was delivered to SMSC but no Delivery Receipt has been received or a Delivery Receipt that could not be interpreted was received.
* undeliverable — Message cannot be delivered.
* deleted — Message has been deleted.


    Possible values: `dispatched`, `aborted`, `rejected`, `delivered`, `failed`, `expired`, `unknown`, `undeliverable`, `deleted`

  - **`properties`** `object` **REQUIRED**
    **One of:**

    - **SMS Delivery Properties** `object`

      A delivery report for SMS.


      - **`error_code`** `string`

        An error code from the short message service center, if applicable.

      - **`is_rcs`** `boolean`

        A boolean describing if the message was delivered as RCS or not.

      - **`sender`** `string` **REQUIRED**

        The number or short code that the message originated from.

      - **`vendor`** `string` **REQUIRED**

        The delivery service for the message.

        Possible values: `CLX`, `TWILIO`

      - **`vendorDeliveryId`** `string` **REQUIRED**

        A unique identifier for the message from the SMS vendor.

    - **MMS Delivery Properties** `object`

      A delivery report for MMS.

      - **`carrier_id`** `string`

        Identifies the carrier the message was sent through.

      - **`error_code`** `string`

        An error code from the short message service center, if applicable.

      - **`handset`** `string`

        The profile of the handset that received the message. This information is only present if the `result_status` is `N102`.

      - **`is_rcs`** `boolean`

        A boolean describing if the message was delivered as RCS or not.

      - **`result_code`** `string` **REQUIRED**

        A status code from the vendor, if applicable.

        Possible values: `N101`, `N102`, `E101`, `E102`

      - **`result_status`** `string`

        Possible values: `Message Sent`, `Message Sent/Delivered`, `Message Failed`, `Message,Sent/Expired`, `Message Sent/Rejected`, `Message Sent/Failed`, `Message Sent/Not Supported`

      - **`sender`** `string` **REQUIRED**

        The number or short code that the message originated from.

      - **`sent_as`** `string`

        Indicates whether the MMS was delivered as MMS (binary) or SMS (HTML).


        Possible values: `MMS`, `SMS`

      - **`tracking_Id`** `string`

        An ID assigned by the delivery service (CLX only).

      - **`vendor`** `string` **REQUIRED**

        The delivery service for the message.

        Possible values: `CLX`


  - **`source`** `string` **REQUIRED**

    Possible values: `API`

  - **`triggering_push`** `object`

    Identifies the push notification that caused the event.

    **OBJECT PROPERTIES**

    - **`campaigns`** `object`

      An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit.

      **OBJECT PROPERTIES**

      - **`categories`** `array[string]`
    - **`group_id`** `string`

      Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification.


      Format: `uuid`

    - **`push_id`** `string` **REQUIRED**

      A unique identifier for a push operation.

      Format: `uuid`

    - **`variant_id`** `integer`

      The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment).

- **`device`** `object` **REQUIRED**

  Device properties for Custom Events with the `delivery_report` interaction type always specify an SMS device.

  **OBJECT PROPERTIES**

  - **`channel`** `string` **REQUIRED**

    The unique, platform-agnostic channel identifier for a device.

  - **`delivery_address`** `string` **REQUIRED**

    The phone number associated with the channel.

  - **`device_type`** `string` **REQUIRED**

    Possible values: `SMS`

- **`id`** `string` **REQUIRED**

  Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate.

- **`occurred`** `string` **REQUIRED**

  When the event occurred.

- **`offset`** `string` **REQUIRED**

  An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason.

- **`processed`** `string` **REQUIRED**

  When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed.

- **`type`** `string` **REQUIRED**

  Possible values: `CUSTOM`


**Used in:**

- [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream)

**Examples**

*Example SMS delivery report Custom Event*

```json
{
  "body": {
    "interaction_type": "delivery_report",
    "name": "dispatched",
    "properties": {
      "sender": 15551234567,
      "vendor": "CLX",
      "vendorDeliveryId": "FENhObMKbCjMOwtw"
    },
    "source": "API",
    "triggering_push": {
      "campaigns": {
        "categories": [
          "New Users"
        ]
      },
      "push_id": "9323b708-7741-4a85-8b1b-e55ad8ce64fc"
    }
  },
  "device": {
    "channel": "db7576c7-6b3d-4f07-b13a-ea3824fea262",
    "delivery_address": "15558675309",
    "device_type": "SMS"
  },
  "id": "48af12e8-6920-4e4e-bef8-b5a6918eec35",
  "occurred": "2019-01-31T17:45:38.700Z",
  "offset": "1000002098217",
  "processed": "2019-01-31T17:45:41.285Z",
  "type": "CUSTOM"
}

```

---