Real-time Data Streaming API

Airship’s Real-time Data Streaming (RTDS) service exposes an event stream for each user. Events may be behavior-driven, system-driven, or custom. Use the RTDS REST API to consume and integrate Airship user event data.

Libraries

Airship maintains open source server libraries to support your integrations with our APIs in multiple languages. Click below for library documentation.

Introduction

Airship’s Real-time Data Streaming API exposes a stream of events describing a user’s experience within a mobile app or browser. Events reflect user action, automated device responses to their environment (e.g. encountering a beacon), and experience-changing actions initiated by app/site publishers, such as sending a push notification.

To consume the event stream, you must issue an authenticated request including a starting point for the stream and optional filter and subset specifications.

The event data is delivered as newline-delimited JSON, with each event on its own line. Each event contains an offset that denotes its location on the stream. If a client disconnects for any reason, it should reconnect with instructions to start at the last offset it successfully processed, to avoid missing any data. For each app key authorized to use Real-time Data Streaming, Airship stores 7 days or 100GB worth of data, whichever comes first.

Base URL

Select the domain (.com or .eu/asnapieu.com) associated with your Airship project.

Authentication

  • HTTP Authentication

    Basic Auth
    Authorization header containing the word Basic followed by a space and a Base64-encoded string generated from your app key and master secret, e.g., Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0. This security type is only accepted by the compliance endpoint.
  • HTTP Authentication

    Bearer Auth
    The authorization header containing your Bearer token, which can be obtained from Airship. Tokens may be revoked at will.

Event Stream

Opens an event stream to your filter specifications.

Open an Event Stream

Connect Request

POST /api/events HTTP/1.1
Authorization: Bearer <authorization token>
X-UA-Appkey: <appkey>
Content-Type: application/json

{
    "filters": [
        {
            "device_types": [
                "android",
                "amazon"
            ],
            "devices": [
                {
                    "channel": "5b389366-7caf-43e2-a19c-6159c7ea9936"
                },
                {
                    "channel": "c8044c8a-d5fa-4e58-91d4-54d0f70b7409"
                },
                {
                    "named_user_id": "George"
                }
            ],
            "latency": 20000000
        },
        {
            "notifications": [
                {
                    "group_id": "a30abf06-7878-4096-9535-b50ac0ad6e8e"
                }
            ],
            "types": [
                "OPEN"
            ]
        }
    ],
    "resume_offset": "MTAwMDAwMDAyMjg1NA",
    "subset": {
        "proportion": 0.3,
        "type": "SAMPLE"
    }
}

Example Response

Status: 200
Content-encoding: gzip
Content-Type: application/vnd.urbanairship+json; version=3;

{"id" : "ff76bb85-74bc-4511-a3bf-11b6117784db", "type": "UNINSTALL", "offset": "MTIzNQ", "occurred": "2015-05-03T02:32:12.088Z", "processed": "2015-05-03T12:12:43.180Z", "device": {"channel":"a61448e1-be63-43ee-84eb-19446ba743f0", "device_type":"ANDROID", "android_channel": "a61448e1-be63-43ee-84eb-19446ba743f0"}}
{"id" : "8e50350e-dd9f-41af-b98e-b0e5d4b27dea","type": "SEND","offset": "NTIxMDM1","occurred": "2015-05-02T02:31:22.088Z","processed": "2015-05-02T02:32:43.181Z","device": {"channel":"5117f2a7-ba58-4981-9456-169959511d1a", "device_type":"IOS", "ios_channel": "5117f2a7-ba58-4981-9456-169959511d1a" },"body": {"push_id": "0c173744-dd35-4b5e-9f7f-2b7e0ce0e36e", "alerting": true}}
{"id" : "ff76bb85-74bc-4511-a3bf-11b6117784db", "type": "UNINSTALL", "offset": "MTIzNQ", "occurred": "2015-05-03T02:32:12.088Z", "processed": "2015-05-03T12:12:43.180Z", "device": {"channel":"a61448e1-be63-43ee-84eb-19446ba743f0", "device_type":"ANDROID", "android_channel": "a61448e1-be63-43ee-84eb-19446ba743f0"}}
{"device":{"channel":"820e4493-e4c9-4577-99bc-a98180599f73","delivery_address":"new.user@urbanairship.com","device_type":"EMAIL"},"id":"00000169-4a14-67b2-1ddd-d9e733622c3a","occurred":"2019-03-04T19:00:45.106Z","offset":"1000001260057","processed":"2019-03-04T19:00:47.094Z","type":"FIRST_OPT_IN"}

POST /api/events

Opens a new event stream according to your request filters. Unlike our other APIs, a request to /api/events/ returns a stream of data, where each line is a JSON object. The response body contains all the events in that stream. Since streams by definition go on forever, Real-time Data Streaming will never end the response without some external reason.

 Note

In the request specification, JSON collection types have semantic meaning.

array: Arrays indicate a boolean "OR". Wherever an array appears in the specification, the resulting stream will contain the events passing any of the conditions defined by the array. An empty array results in a 400 response.

object: Object attributes indicate a boolean "AND". All conditions in the object must be satisfied in order for an event to be written to the response. If you would like all events to pass the condition the attribute defines, omit the attribute. If an unexpected attribute appears on an event, a status code 400 response will be returned.

 Important

Airship will occasionally add:

  • New properties to existing objects.

  • New event types, which will be JSON objects with new values for the type field.

Your integration must be tolerant of these kinds of changes.

Security:

header PARAMETERS
  • X-UA-Appkey : String Required

    The App Key for the app you want to return events from.

    The application key.

Request Body

  • Content-Type: application/json

    Object

    The request body defines the events you want to return in the event stream. You can define position, subset and filter specifications in each request submitted to the stream. Filters are positive statements about what events the client should return. The subset specification returns a representative portion of the stream.

    OBJECT PROPERTIES
    • filters : Request Filters

      An array of filter objects defining the events you want to see in the event stream. A filter object defines a function that either passes or fails an event. Events are included in the response if they pass any of the functions defined by the objects in the array.

    • resume_offset : String

      The offset where the stream should begin. The offset is an identifier relevant only to Real-time Data Streaming. The first event in the stream will be the next element satisfying the filter and subset conditions with an offset field greater than this value. Only specify resume_offset if start is absent.

    • start : String

      Specifies that the stream should start at the beginning or the end of the application’s data window. Only specify one of ‘resume_offset’ and ‘start.’

      Possible values: EARLIEST, LATEST

    • subset : Request Subset

      Use subsets to return a proportion of the event stream and not all events meeting your other criteria. The subset object defines the proportion of the event stream that you want to return.

Responses

  • 200

    The response to a successful request is an unending stream of newline delimited JSON. Each non-empty line in the response represents a single event.

    This response body is of arbitrarily large size. As long as the connection is open, Airship will continue to write to the data stream. If no events have been dispatched down a connection for some time, the API will write to the connection to prevent it from being closed for inactivity. By default, only a blank line (a single newline character) will be written. If the enable_offset_updates field on the request is true, then instead of a blank line, an event will be written with type OFFSET_UPDATE. These events have no body or device field, and always have occurred and processed times indicating when they were sent. The offset field will contain the offset of the last event considered for inclusion in the stream whether or not it was actually sent. This may be useful to track position in the stream when using a filter which removes much of it.

    These events should not be stored, and will be different for every connection even if requests are identical. OFFSET_UPDATE events are not subject to filters, and if requested will be delivered regardless of those specified. You should always check the type field before handling any delivered event.

    If you receive no data or new line characters for ninety seconds, close the connection and reconnect.

    RESPONSE BODY
    • Content-Type: application/vnd.urbanairship+x-ndjson; version=3;

      One of
      • Push Body

        Occurs when you initiate a push, automation, or journey.

        Airship fulfills delivery over a time interval with a number of child pushes, each with a unique Push ID and a common Group ID. There is no guarantee that push body events (defined in Push Body Event) for the child pushes fulfilling a group will appear in the stream.

        Note: When you start, pause, or publish a journey, Airship emits a push_body event for the journey itself, and each message contained within the journey (i.e. messages +1). After you start a journey, Airship does not issue subsequent push_body events for the journey unless you pause or publish changes to the journey.

      • Open

        Occurs when a user opens your app.

      • Send

        Occurs whenever a push notification is sent to a device identified in the audience selector of a message.

      • Send Rejected

        Occurs when a push fails during communication with a third party, like APNS or GCM. This typically indicates that the user has uninstalled the app or otherwise invalidated the last-registered credentials stored in Airship. The event contains the rejected push and the group, variant, or campaigns the push belonged to.

        Device information for the device that did not receive the push is included with SEND_REJECTED events.

      • Send Aborted

        Occurs when a push is dropped from our system before delivery is attempted. This can happen if you are using External Data Feeds to personalize a message and an error was encountered or the feed returned a non-successful response, or when reaching a Message Limit.

        Device information for the device that did not receive the push is included with SEND_ABORTED events.

      • Control

        Occurs when a device is excluded from a push because it was arbitrarily selected as a member of a control group. Membership in a control group indicates what would’ve happened if you did not send a message to a user at all. This occurs for A/B Test-related pushes only.

      • Close

        Occurs when a user closes the app. Close events are often latent, as they aren’t sent back to Airship until the user activates the app again.

      • Rich Delivery

        Occurs when a rich message is delivered to a user’s inbox.

        Even though rich push deliveries may or may not cause an alert on the user’s lock screen, they are always associated with a push identifier in the Airship system.

      • Rich Read

        Occurs when a user reads a rich message in their inbox.

      • Rich Delete

        Occurs when a user deletes a rich message from their inbox.

      • Custom

        Represents custom events that are either emmitted from the Airship SDK or submitted through the Custom Events API. You can configure custom events yourself. There are also several CUSTOM-type events for email and SMS that are defined by Airship.

        In general, you can expect device information if the event source is SDK or if the event is one of the defined email or SMS events (as defined by event_type).

      • Location

        An event declaring the device to be at a particular latitude and longitude.

      • Tag Change

        Occurs when tags change for a device.

      • First Open

        This event occurs when a user opens an Airship-integrated app for the first time.

      • First opt-in

        This event appears in the stream when a channel is first opted in. This event is specific to email (commercial), sms and open channels.

      • Region Event

        Region Events are emitted when a device enters or exits a geofence or the range of any of a set of bluetooth beacons. Region events require a Gimbal integration. Events for Gimbal customers include the Gimbal application instance identifer as com.urbanairship.gimbal.aii within the identifiers object.

      • Screen Viewed

        Occurs when a user has finished viewing a screen. It is up to you to instrument your application with names for each screen. Doing so will allow you to deterimine the user’s path by filtering on the fields in the table below.

      • In-App Message Display

        Occurs when an in-app message is displayed to a user. Because the event pertains to a specific device, the device information object will be populated.

      • In-App Message Expiration

        Occurs when a new message has taken the place of another message, a message has passed its expiration, or because displaying the message in-app would be redundant. This event type may be latent; it is not emitted until the app becomes active.

      • In-App Message Resolution

        Occurs when an In-App Message is cleared from the display, either by user action or timeout. Because this event pertains to an individual device, the device information object will be present.

      • Uninstall

        Occurs when a user uninstalls an Airship-integrated app in response to a push.

      • Web Click Event

        Occurs when user interacts with a web notification, e.g. clicked on or tapped it. Web Click events have a device attribute on the event indicating the channel that was the target of the notification. The body of a Web Click Event is an Associated Push object.

      • Web Session Event

        Occurs when an opted in user begins interacting with a website. Web Session events have a device attribute, indicating the channel associated with the user.

      • Subscription Event

        SUBSCRIPTION events reflect changes to users' subscription preferences — reflected in opt_in and opt_out values. These events help you track a user’s subscription status in the system and the total number of subscribers.

      • Compliance Event

        Events relating to regulatory compliance for email and SMS channels.

      • Mobile Originated Event

        Represents a message action that originated from a user — like an inbound SMS or email.

      • Short Link Click Event

        Occurs when a user taps or “clicks” an Airship-shortened link in an SMS or MMS message.

      • Attribute Operation Event

        Attribute Operation events indicate a change in the device’s attributes. Because attribute operations are related to a device, they will have a device field.

        If you set an attribute on a named user, Airship records events for each device associated with the named user.

  • 402

    Like other UA applications, Real-time Data Streaming supports a limited number of simultaneous connections. If you exceed this number, you may receive this response.

  • 404

    We do not have data for the specified App key. This is likely because we have yet to ingress or generate any data for your app.

Compliance Event Stream

The Compliance Event Stream provides real-time access to COMPLIANCE type events. This endpoint is open to all Airship users.

Open a Compliance Event Stream

Compliance Event Stream Request

POST /api/events/general HTTP/1.1
Authorization: Basic <master authorization string>
X-UA-Appkey: <appkey>

{
  "start":"LATEST",
  "enable_offset_updates": true
}

Example Response

Status: 200
Content-encoding: gzip
Content-Type: application/vnd.urbanairship+json; version=3;

{
  "id": "9781ff2e-fa4a-4fa8-bd9d-41f318c48963",
  "offset": "1000001778910",
  "occurred": "2018-11-28T00:02:41.794Z",
  "processed": "2018-11-28T00:02:45.270Z",
  "device": {
      "channel": "5a39b6d8-0a5a-4c2b-a4a0-3d4a71e5254b",
      "device_type": "EMAIL",
      "delivery_address": "bogus@email.com"
  },
  "body": {
      "event_type": "bounce",
      "properties": {
          "bounce_event_type": "bounce",
          "sender": "msprvs1=17870ayYKWpBI=bounces-179492-4@spmailtechnolo.com",
          "subject": "You there?",
          "email": "bogus@email.com",
          "bounce_class": "10"
      }
  },
  "type": "COMPLIANCE"
}

POST /api/events/general

Opens a stream delivering events proving data-safety regulation compliance for email and SMS channel-related events (registration, unsubscription, etc).

Unlike a standard event stream, a compliance event stream is uses basic authorization (like API calls to https://go.urbanairship.com/api)

Security:

header PARAMETERS
  • X-UA-Appkey : String Required

    The App Key for the app you want to return compliance events for.

    The application key.

Request Body

  • Content-Type: application/json

    Object

    A request for compliance events is much like a request to /api/events, but has a limited scope.

    OBJECT PROPERTIES
    • filters : Array [Object]

      An array of filter objects defining the events you want to appear in the event stream.

      ARRAY ITEM
      • OBJECT PROPERTIES
        • device_types : Array [String]

          Returns events pertaining to devices on the specified platform(s).

        • latency : Integer

          The number of milliseconds between the current time and when the event(s) you want to return occured. If an event occurred more than latency milliseconds ago, it is filtered out of the event stream. Format: milliseconds

    • resume_offset : String

      The offset where the stream should begin. The offset is an identifier relevant only to the data stream. The first event in the stream will be the next element satisfying the filter and subset conditions with an offset field greater than this value. Only specify resume_offset if start is absent.

    • start : String

      Specifies that the stream should start at the beginning or the end of the application’s data window. Only specify one of ‘resume_offset’ and ‘start.’

      Possible values: EARLIEST, LATEST

    • subset : Request Subset

      Use subsets to return a proportion of the event stream and not all events meeting your other criteria. The subset object defines the proportion of the event stream that you want to return.

Responses

  • 200

    The response to a successful request is an unending stream of newline delimited JSON. Each non-empty line in the response represents a single compliance event. Unlike events in a normal event stream, this endpoint returns events of the compliance type, and is open to SMS and email customers. As long as the connection is open, Airship will continue to write to the event stream.

    If a stream records no events for a period of time, the API will write a blank line (a single newline character) to the connection to prevent it from being closed for inactivity. If the enable_offset_updates field on the request is true, then the blank line is replaced with an OFFSET_UPDATE event. These events have no body or device field, and always have occurred and processed times indicating when they were sent. The offset field will contain the offset of the last event considered for inclusion in the stream whether or not it was actually sent. This may be useful to track position in the stream when using a filter which removes much of it.

    You should not store these events; they will be different for every connection even if requests are identical. OFFSET_UPDATE events are not subject to filters, and are delivered even if not specified in the list of events you want to return. You should always check the type field before handling any delivered event.

    If you do not receive data or new line characters for ninety seconds, close the connection and reconnect.

    RESPONSE BODY
    • Content-Type: application/vnd.urbanairship+x-ndjson; version=3;

      Events relating to regulatory compliance for email and SMS channels.

Data Formats

Events

Contains information about events organized by type. Some events contain additional subtypes or device information.

Attribute Operation Event

Example Attribute Operation Event

{
  "id": "00000173-bb88-8804-b6ec-a40f4ae36648",
  "offset": "1000059326194",
  "occurred": "2020-08-04T22:12:33.924Z",
  "processed": "2020-08-04T22:12:37.672Z",
  "device": {
      "android_channel": "b57f0e3c-da10-4a2b-99d2-5fe2cb30cad3",
      "channel": "b57f0e3c-da10-4a2b-99d2-5fe2cb30cad3",
      "device_type": "ANDROID",
      "named_user_id": "cool_user",
      "attributes": {
        "locale_variant": "",
        "app_version": "2020-02-10T222436-staging",
        "device_model": "Pixel 2 XL",
        "connection_type": "WIFI",
        "app_package_name": "com.urbanairship.goat.staging",
        "iana_timezone": "America/Los_Angeles",
        "push_opt_in": "true",
        "locale_country_code": "US",
        "device_os": "10",
        "locale_timezone": "-25200",
        "locale_language_code": "en",
        "location_enabled": "false",
        "background_push_enabled": "true",
        "ua_sdk_version": "12.2.0",
        "location_permission": "NOT_ALLOWED"
      }
  },
  "body": {
      "set": [
        {
            "key": "first_name",
            "value": "Pierre"
        }
      ]
  },
  "type": "ATTRIBUTE_OPERATION"
}
  • Attribute Operation events indicate a change in the device’s attributes. Because attribute operations are related to a device, they will have a device field.

    If you set an attribute on a named user, Airship records events for each device associated with the named user.

    OBJECT PROPERTIES
    • body : ObjectRequired

      Min properties: 1

      OBJECT PROPERTIES
      • remove : Array [Object]

        The attributes removed from the device in this event. Min items: 1

        ARRAY ITEM
        • OBJECT PROPERTIES
          • key : StringRequired

            The attribute being removed.

      • set : Array [Object]

        Min items: 1

        ARRAY ITEM
        • The attributes set on the device in this event.

          OBJECT PROPERTIES
          • key : StringRequired

            The attribute being set.

          • value : AnyRequired

            The value for the attribute.

            One of
            • String

            • Number

    • device : AnyRequired

      One of
    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: ATTRIBUTE_OPERATION

Close

Example Close Event

{
  "id": "51dd7c1c-5621-11e9-9601-0242539d70ef",
  "offset": "1000022467557",
  "occurred": "2019-03-29T21:42:21.245Z",
  "processed": "2019-04-03T15:10:23.828Z",
  "device": {
    "ios_channel": "a61448e1-be63-43ee-84eb-19446ba743f0",
    "channel": "a61448e1-be63-43ee-84eb-19446ba743f0",
    "device_type": "IOS",
    "named_user_id": "cooluser",
    "identifiers": {
      "com.urbanairship.limited_ad_tracking_enabled": "true",
      "session_id": "B147E0CE-272E-4047-A79C-30D02A2F213D",
      "GA_CID": "a61448e1-be63-43ee-84eb-19446ba743f0",
      "com.urbanairship.idfa": "A76E6F83-4F4A-47E2-BFDD-72BED91D2D1F",
      "com.urbanairship.vendor": "ED496B1A-43F1-45A9-A7C1-80125DE8A5B1"
    },
    "attributes": {
      "locale_variant": "",
      "app_version": "542",
      "device_model": "iPhone7,2",
      "connection_type": "WIFI",
      "app_package_name": "com.urbanairship.appname",
      "iana_timezone": "America/Los_Angeles",
      "push_opt_in": "true",
      "locale_country_code": "US",
      "device_os": "11.4",
      "locale_timezone": "-25200",
      "carrier": "AT&T",
      "locale_language_code": "en",
      "location_enabled": "false",
      "background_push_enabled": "true",
      "ua_sdk_version": "10.2.0",
      "location_permission": "ALWAYS_ALLOWED"
    }
  },
  "body": {
    "session_id": "61acb6c9-527b-4632-b789-a3e6085b094e"
  },
  "type": "CLOSE"
}
  • Occurs when a user closes the app. Close events are often latent, as they aren’t sent back to Airship until the user activates the app again.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • session_id : String

        Represents the “session” of user activity. Absent if the application was initialized while backgrounded. Format: uuid

    • device : App Device InformationRequired

      Information about app users generated by the SDK.

    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: CLOSE

Compliance Event

Example Compliance Event Stream

{
  "id": "9781ff2e-fa4a-4fa8-bd9d-41f318c48963",
  "offset": "1000001778910",
  "occurred": "2018-11-28T00:02:41.794Z",
  "processed": "2018-11-28T00:02:45.270Z",
  "device": {
      "channel": "5a39b6d8-0a5a-4c2b-a4a0-3d4a71e5254b",
      "device_type": "EMAIL",
      "delivery_address": "bogus@email.com"
  },
  "body": {
      "event_type": "bounce",
      "properties": {
          "bounce_event_type": "bounce",
          "sender": "msprvs1=17870ayYKWpBI=bounces-179492-4@spmailtechnolo.com",
          "subject": "You there?",
          "email": "bogus@email.com",
          "bounce_class": "10"
      }
  },
  "type": "COMPLIANCE"
}
  • Events relating to regulatory compliance for email and SMS channels.

    All of
    • Object

      OBJECT PROPERTIES
      • id : StringRequired

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

        When the event occurred.

      • offset : String

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

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

      • type : StringRequired

        Compliance events are the only types of events returned by this event stream.

        Possible values: COMPLIANCE

    • One of
      • Email Bounce Event

        An event that occurs when an email could not be delivered to a particular address. The bounce_class can provide more information about why the message bounced.

      • Email Create-and-Send Event Body

        An event that occurs for email addresses used as a part of a create-and-send message.

      • Email Registration Event

        An event that occurs when users register to receive email messages.

      • Email Unsubscribe Event

        A compliance event representing a user who unsubscribed from your email notifications.

      • SMS API Initiated Opt In Event

        Occurs when an SMS user is registered via the SMS Channel Registration API without an opted_in value — indicating that the user has initiated, but not completed, the registration process. While this event contains a channel_id, you cannot send messages to this channel until the associated user completes the opt-in process (indicated by a mobile_opt_in event).

      • SMS Carrier Deactivation Event

        Occurs when an MSISDN is deactivated by a carrier. This event type does not contain additional properties.

      • SMS Create-and-Send Event

        An event that occurs for SMS channels used as a part of a create-and-send message.

      • SMS Custom Keyword Response Event

        Occurs when a mobile-originated keyword is matched, and elicits a custom response.

      • SMS Mobile Create Channel Event

        If a channel does not exist for the MSISDN/sender combination and your account is configured to create a channel if none exists in such instances, we will emit this event. The resulting channel will necessarily be opted out, awaiting an opt-in action by the user.

      • SMS Mobile Keyword Matched Event

        Occurs when a mobile-originated message contains a recognized keyword.

      • SMS Mobile Keyword Unmatched Event

        Occurs when a mobile-originated message does not contain a recognized keyword.

      • SMS Mobile Opt In Event

        Occurs when a user opts in to text messages via a keyword.

      • SMS Mobile Opt Out Event

        Occurs when a user sends a MO message that matches a keyword with an opt-out action. If present, this event would supplant a mobile_keyword_matched event.

      • SMS Opted Out Event

        Occurs when a user is opted out of an SMS audience via the Airship API, i.e., not via an opt-out keyword. This event type does not contain additional properties.

      • SMS Registration Event

        Occurs when a user opts in to receive SMS messages from you, via a call to the SMS registration API.

      • SMS Uninstalled Event

        Occurs when the SMS uninstall API is called.

      • SMS Mobile Terminated Message Event

        Occurs when Airship sends an SMS message to a user. The message represented by this event could be a response to an individual mobile-originated (MO) message, or a message initiated from the Airship UI/API.

Control

Example Control Event

{
  "id" : "ff76bb85-74bc-4511-a3bf-11b6117784db",
  "type": "CONTROL",
  "offset": "MTIzNQ",
  "occurred": "2015-05-03T02:32:12.088Z",
  "processed": "2015-05-03T12:12:43.180Z",
  "device": {
      "channel":"a61448e1-be63-43ee-84eb-19446ba743f0",
      "device_type":"ANDROID",
      "android_channel": "a61448e1-be63-43ee-84eb-19446ba743f0"
    },
  "body:" {
    "push_id": "c91d9e1b-605f-4bad-a45d-cdf3e6e0773f",
    "group_id": "3eec7de4-4b19-436e-ad15-88278f9ddb82"
    }
  }
  • Occurs when a device is excluded from a push because it was arbitrarily selected as a member of a control group. Membership in a control group indicates what would’ve happened if you did not send a message to a user at all. This occurs for A/B Test-related pushes only.

    OBJECT PROPERTIES
    • body : ObjectRequired

      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

        A unique identifier for a push operation. Format: uuid

    • device : AnyRequired

      One of
    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: CONTROL

Custom

Example Custom Event from API (Shoe Sale)

{
  "name" : "shoe-purchase",
  "value" : 239.85,
  "source": "api"
  "transaction" : "Selling all the shoes",
  "session_id": "cfe467a6-ca70-40dd-8c1f-07b2f644935e",
  "properties": {
    "description": "Sneaker purchase",
    "brand": "Victory Sneakers",
    "colors": ["red","blue"],
    "items": [
      {
          "text": "New Line Sneakers",
          "price": "$ 79.95"
      },
      {
          "text": "Old Line Sneakers",
          "price": "$ 79.95"
      },
      {
          "text": "Blue Line Sneakers",
          "price": "$ 79.95"
      }
    ],
    "name": "Hugh Manbeing",
    "userLocation": {
      "state": "CO",
      "zip": "80202"
    }
  }
}

Example Custom Event from SDK (Shoe Sale)

{
  "name" : "shoe-purchase",
  "value" : 60.000000,
  "source": "sdk"
  "interaction_type" : "Landing Page",
  "interaction_id" : "d01d0380-da2e-11e3-8519-90e2ba299b38",
  "customer_id" : "George@hotmail.com",
  "transaction" : "Selling all the shoes",
  "session_id": "cfe467a6-ca70-40dd-8c1f-07b2f644935e",
  "last_delivered": {
    "push_id": "6e3339ce-529c-42e4-a2f6-7546f81c9828"
  },
  "triggering_push": {
    "push_id": "c2f6c5c5-f353-49c0-b5f7-6e87cf9b1a06",
    "group_id": "8ea2abd6-dbc7-475a-9c57-fb31c7e2999b"
  },
  "properties": {
    "coolest-identifier": "123-cool-cat-321",
    "ltv": false,
    "category": "womens_shoes",
    "id": 1267,
    "description": "plaid canvas",
    "brand": "hipster",
    "new_item": true
  }
}
  • Represents custom events that are either emmitted from the Airship SDK or submitted through the Custom Events API. You can configure custom events yourself. There are also several CUSTOM-type events for email and SMS that are defined by Airship.

    In general, you can expect device information if the event source is SDK or if the event is one of the defined email or SMS events (as defined by event_type).

    All of
    • Object

      OBJECT PROPERTIES
      • id : StringRequired

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

        When the event occurred.

      • offset : StringRequired

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

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

      • type : StringRequired

        Possible values: CUSTOM

    • One of
      • Email Delivery Event

        Occurs when the remote MTA (email server) acknowledges receipt of a message.

      • Email Injection Event

        This event occurs when the provider (SparkPost) receives a message — typically when a member of the audience responds to an email.

      • Email Open Event

        Occurs when a recipient opens an email, rendering a tracking pixel at the bottom of the message. If a message is truncated by a client or email provider, a user may have to open it in a separate window to render the tracking pixel (and register this event).

      • Email Delay Event

        Occurs when a mailbox provider temporarily rejects an email. In general, this event indicates that the provider will attempt to resend the message.

      • Email Bounce Event

        Occurs when an email could not be delivered to an address. The bounce_class provides additional information about the reason your message bounced. This event occurs in conjunction with a similar COMPLIANCE event.

      • Email Click Event

        Occurs when a recipient clicks a tracked link in a message. Tracked links are redirected through the provider’s click-tracking server to record the event.

      • Email Unsubscribe Link Event

        Occurs when a user clicks an unsubscribe link in an email you sent.

      • SMS 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.

      • General Custom Event : Object

        OBJECT PROPERTIES
        • body : ObjectRequired

          OBJECT PROPERTIES
          • customer_id : String

            An external customer-side id, such as an email address. Absent if empty.

          • interaction_id : String

            An Airship identifier uniquely identifying the interaction. May be absent.

          • interaction_type : String

            The type of interaction as set by the UA SDK. Values determine whether the interaction triggered an event from the message center (ua_mcrap), a landing page (ua_landing_page), or an interactive notification (ua_interactive_notification). Possible values: ua_mcrap, ua_landing_page, ua_interactive_notification

          • last_delivered : Object

            Identifies the last push notification the audience received before the event. Absent if the last push occurred more than 12 hours ago.

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

              A unique identifier for a push operation. Format: uuid

            • time : String

              The UTC time when the push occurred.

            • 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).

          • name : StringRequired

            A plain-text name given to the event.

          • properties : Object

            Supports up to 100 key/value pairs that describe custom event properties. If the event has no custom properties, this field is absent. Max properties: 100

          • session_id : String

            Represents the “session” of user activity. Absent if the application was initialized while backgrounded. Format: uuid

          • source : StringRequired

            The event source. SDK indicates an event sent from the UA SDK. API indicates an event created by request against the [Server Side Custom Events API]{{< relref “api/ua/#server-side-custom-events” >}}. Possible values: SDK, API

          • transaction : String

            If the event is one in a series representing a single transaction, use the value in this field to tie events together.

          • triggering_push : Object

            The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.

            An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.

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

              A unique identifier for a push operation. Format: uuid

            • time : String

              The UTC time when the push occurred.

            • 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).

          • value : Number

            Populated if the event is associated with a count or amount. Airship treats this field as a representation of money. The value field respects six digits of precision to the right of the decimal point.

        • device : ObjectRequired

          OBJECT PROPERTIES
          • channel : StringRequired

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

          • device_type : StringRequired

            The type of device the event was generated from. Possible values: OPEN, WEB, ANDROID, IOS, AMAZON, EMAIL, SMS

First Open

Example FIRST_OPEN Event

{
  "device": {
    "ios_channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110",
    "channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110",
    "device_type": "IOS",
  },
  "id": "00000169-4a14-67b2-1ddd-d9e733622c3a",
  "occurred": "2019-03-04T19:00:45.106Z",
  "offset": "1000001260057",
  "processed": "2019-03-04T19:00:47.094Z",
  "type": "FIRST_OPEN"
}
  • This event occurs when a user opens an Airship-integrated app for the first time.

    OBJECT PROPERTIES
    • device : AnyRequired

      One of
    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: FIRST_OPEN

First opt-in

Example FIRST_OPT_IN Event

{
  "device": {
    "channel": "820e4493-e4c9-4577-99bc-a98180599f73",
    "delivery_address": "new.user@urbanairship.com",
    "device_type": "EMAIL"
  },
  "id": "00000169-4a14-67b2-1ddd-d9e733622c3a",
  "occurred": "2019-03-04T19:00:45.106Z",
  "offset": "1000001260057",
  "processed": "2019-03-04T19:00:47.094Z",
  "type": "FIRST_OPT_IN"
}
  • This event appears in the stream when a channel is first opted in. This event is specific to email (commercial), sms and open channels.

    OBJECT PROPERTIES
    • device : AnyRequired

      One of
    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: FIRST_OPT_IN

In-App Message Display

Example In-App Message Display Event

{
  "id": "51dd7c1c-5621-11e9-9601-0242539d70ef",
  "offset": "1000022467557",
  "occurred": "2019-03-29T21:42:21.245Z",
  "processed": "2019-04-03T15:10:23.828Z",
  "device": {
    "ios_channel": "a61448e1-be63-43ee-84eb-19446ba743f0",
    "channel": "a61448e1-be63-43ee-84eb-19446ba743f0",
    "device_type": "IOS",
    "named_user_id": "cooluser",
    "identifiers": {
      "com.urbanairship.limited_ad_tracking_enabled": "true",
      "session_id": "B147E0CE-272E-4047-A79C-30D02A2F213D",
      "GA_CID": "a61448e1-be63-43ee-84eb-19446ba743f0",
      "com.urbanairship.idfa": "A76E6F83-4F4A-47E2-BFDD-72BED91D2D1F",
      "com.urbanairship.vendor": "ED496B1A-43F1-45A9-A7C1-80125DE8A5B1"
      },
    "attributes": {
      "locale_variant": "",
      "app_version": "542",
      "device_model": "iPhone7,2",
      "connection_type": "WIFI",
      "app_package_name": "com.urbanairship.appname",
      "iana_timezone": "America/Los_Angeles",
      "push_opt_in": "true",
      "locale_country_code": "US",
      "device_os": "11.4",
      "locale_timezone": "-25200",
      "carrier": "AT&T",
      "locale_language_code": "en",
      "location_enabled": "false",
      "background_push_enabled": "true",
      "ua_sdk_version": "10.2.0",
      "location_permission": "ALWAYS_ALLOWED"
      }
    },
    "body": {
      "push_id": "68be9eba-3f3e-4763-bbd1-c921a164af1b",
      "group_id": "49e59f68-d58c-4a2f-86ab-112f52e3c5d2",
      "variant_id": 5,
      "session_id": "cfe467a6-ca70-40dd-8c1f-07b2f644935e",
      "triggering_push": {
        "push_id": "18c0f649-2330-4fb0-a9fa-ad029f5f4e0e",
        "group_id": "c4c89025-0d25-434c-8040-283990585f01"
      }
    },
  "type": "IN_APP_MESSAGE_DISPLAY"
}
  • Occurs when an in-app message is displayed to a user. Because the event pertains to a specific device, the device information object will be populated.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • app_defined_id : String

        An identifier defined by the application if the In-App Message was created by the application logic, not the UA system. If this field is present, the event body will not contain push_id, group_id, variant_id, or triggering_push fields.

      • 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

        A unique identifier for a push operation. Format: uuid

      • session_id : String

        Represents the “session” of user activity. Absent if the application was initialized while backgrounded. Format: uuid

      • triggering_push : Object

        The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.

        An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.

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

          A unique identifier for a push operation. Format: uuid

        • time : String

          The UTC time when the push occurred.

        • 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).

      • 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 : App Device InformationRequired

      Information about app users generated by the SDK.

    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: IN_APP_MESSAGE_DISPLAY

In-App Message Expiration

Example In-App Message Expiration Event

{
  "id": "910fea50-5d42-1159-b702-024288f4e1d3",
  "offset": "1000022468589",
  "occurred": "2019-04-03T18:59:02.246Z",
  "processed": "2019-04-03T19:10:26.301Z",
  "device": {
    "android_channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe",
    "channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe",
    "device_type": "ANDROID",
    "identifiers": {
      "com.urbanairship.gimbal.aii": "2471037d-71d8-4229-a40f-df719f1af914",
      "session_id": "54204a73-7a95-4ffc-8051-bf230d086e19",
      "GA_CID": "90d56c80-f31f-49fd-87b0-20deb3d2602a"
    },
    "attributes": {
      "locale_variant": "",
      "app_version": "dev",
      "device_model": "Android SDK built for x86",
      "connection_type": "WIFI",
      "app_package_name": "com.urbanairship.goat",
      "iana_timezone": "America/Los_Angeles",
      "push_opt_in": "true",
      "locale_country_code": "US",
      "device_os": "9",
      "locale_timezone": "-25200",
      "carrier": "Android",
      "locale_language_code": "en",
      "location_enabled": "false",
      "background_push_enabled": "true",
      "ua_sdk_version": "9.7.0",
      "location_permission": "NOT_ALLOWED"
    }
  },
  "body": {
    "push_id": "a1fe5f2a-1d51-4f3a-a77b-35018031741d",
    "session_id": "3514bd74-bfa8-149e-9c12-a44794994ca8",
    "type": "EXPIRED",
    "time_expired": "1970-01-01T00:00:00.000Z"
  },
  "type": "IN_APP_MESSAGE_EXPIRATION"
}
  • Occurs when a new message has taken the place of another message, a message has passed its expiration, or because displaying the message in-app would be redundant. This event type may be latent; it is not emitted until the app becomes active.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • app_defined_id : String

        An identifier defined by the application if the In-App Message was created by the application logic, not the UA system. If this field is present, the event body will not contain push_id, group_id, variant_id, or triggering_push fields.

      • 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

        A unique identifier for a push operation. Format: uuid

      • replacing_push : Object

        The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.

        An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.

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

          A unique identifier for a push operation. Format: uuid

        • time : String

          The UTC time when the push occurred.

        • 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).

      • session_id : String

        Represents the “session” of user activity. Absent if the application was initialized while backgrounded. Format: uuid

      • time_expired : String

        The date-time when the message was set to expire.

      • time_sent : String

        The date-time when the in-app message payload was sent to the device.

      • triggering_push : Object

        The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.

        An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.

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

          A unique identifier for a push operation. Format: uuid

        • time : String

          The UTC time when the push occurred.

        • 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).

      • type : String

        Indicates how the In-App Message expired.

        • REPLACED: The In-App message was replaced by a more current one. If type is REPLACED, the replacing_push key will be present.
        • EXPIRED: The In-App message exceeded it’s expiration date. If type is EXPIRED, then the time key will be present.
        • ALREADY_DISPLAYED: The message was opened directly (either from the lock screen or notification center). The Airship SDK will NOT display it again in the app, because the user is guaranteed to have seen it. Possible values: REPLACED, EXPIRED, ALREADY_DISPLAYED

      • 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).

    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: IN_APP_MESSAGE_EXPIRATION

In-App Message Resolution

Example In-App Message Resolution Event

{
  "id": "910fea50-5d42-1159-b702-024288f4e1d3",
  "offset": "1000022468589",
  "occurred": "2019-04-03T18:59:02.246Z",
  "processed": "2019-04-03T19:10:26.301Z",
  "device": {
    "android_channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe",
    "channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe",
    "device_type": "ANDROID",
    "identifiers": {
      "com.urbanairship.gimbal.aii": "2471037d-71d8-4229-a40f-df719f1af914",
      "session_id": "54204a73-7a95-4ffc-8051-bf230d086e19",
      "GA_CID": "90d56c80-f31f-49fd-87b0-20deb3d2602a"
    },
    "attributes": {
      "locale_variant": "",
      "app_version": "dev",
      "device_model": "Android SDK built for x86",
      "connection_type": "WIFI",
      "app_package_name": "com.urbanairship.goat",
      "iana_timezone": "America/Los_Angeles",
      "push_opt_in": "true",
      "locale_country_code": "US",
      "device_os": "9",
      "locale_timezone": "-25200",
      "carrier": "Android",
      "locale_language_code": "en",
      "location_enabled": "false",
      "background_push_enabled": "true",
      "ua_sdk_version": "9.7.0",
      "location_permission": "NOT_ALLOWED"
    }
  },
  "body": {
   "push_id": "86ee0a6e-a46a-4bbe-a3d1-804891baaee4",
   "group_id": "68991b8d-0d6b-4e05-bc62-2cdec2085c18",
   "time_sent": "2019-03-03T19:10:26.301Z",
   "type": "BUTTON_CLICK",
   "button_id": "yes",
   "button_description": "Yes",
   "button_group": "ua_yes_no_background",
   "duration": 10000000000
  },
  "type": "IN_APP_MESSAGE_RESOLUTION"
}
  • Occurs when an In-App Message is cleared from the display, either by user action or timeout. Because this event pertains to an individual device, the device information object will be present.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • app_defined_id : String

        An identifier defined by the application if the In-App Message was created by the application logic, not the UA system. If this field is present, the event body will not contain push_id, group_id, variant_id, or triggering_push fields.

      • button_description : String

        The title of the button the user interacted with. Present if type is set to BUTTON_CLICK.

      • button_group : String

        A category associated with the message. Present if type is set to BUTTON_CLICK.

      • button_id : String

        A unique identifier for the button. Present if type is set to BUTTON_CLICK.

      • duration : Integer

        The number of milliseconds that the user was on the screen.

      • 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

        A unique identifier for a push operation. Format: uuid

      • session_id : String

        Represents the “session” of user activity. Absent if the application was initialized while backgrounded. Format: uuid

      • time_sent : String

        The date-time when the in-app message payload was sent to the device.

      • triggering_push : Object

        The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.

        An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.

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

          A unique identifier for a push operation. Format: uuid

        • time : String

          The UTC time when the push occurred.

        • 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).

      • type : String

        Indicates how the In-App Message was resolved.

        • ‘BUTTON_CLICK’: The user clicked/tapped a button in the message. This type is accompanied by additional fields.
        • ‘MESSAGE_CLICK’: The user clicked/tapped a part of the message, but not a button.
        • ‘TIMED_OUT’: The user ignored the notification, and it dismissed itself after an interval of time.
        • ‘USER_DISMISSED’: The user clicked/tapped “X” to close the message or closed it using the swipe gesture. Possible values: BUTTON_CLICK, MESSAGE_CLICK, TIMED_OUT, USER_DISMISSED

      • 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 : App Device InformationRequired

      Information about app users generated by the SDK.

    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: IN_APP_MESSAGE_RESOLUTION

Location

Example LOCATION Event

{
  "id": "910fea50-5d42-1159-b702-024288f4e1d3",
  "offset": "1000022468589",
  "occurred": "2019-04-03T18:59:02.246Z",
  "processed": "2019-04-03T19:10:26.301Z",
  "device": {
    "android_channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe",
    "channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe",
    "device_type": "ANDROID",
    "identifiers": {
      "com.urbanairship.gimbal.aii": "2471037d-71d8-4229-a40f-df719f1af914",
      "session_id": "54204a73-7a95-4ffc-8051-bf230d086e19",
      "GA_CID": "90d56c80-f31f-49fd-87b0-20deb3d2602a"
    },
    "attributes": {
      "locale_variant": "",
      "app_version": "dev",
      "device_model": "Android SDK built for x86",
      "connection_type": "WIFI",
      "app_package_name": "com.urbanairship.goat",
      "iana_timezone": "America/Los_Angeles",
      "push_opt_in": "true",
      "locale_country_code": "US",
      "device_os": "9",
      "locale_timezone": "-25200",
      "carrier": "Android",
      "locale_language_code": "en",
      "location_enabled": "false",
      "background_push_enabled": "true",
      "ua_sdk_version": "9.7.0",
      "location_permission": "ALWAYS_ALLOWED"
    }
  },
  "body": {
    "latitude": "51.5033630",
    "longitude": "-0.1276250",
    "foreground": true,
    "session_id": "ecd3741d-92c4-469b-b42c-888e40a121d3"
  },
  "type": "LOCATION"
}
  • An event declaring the device to be at a particular latitude and longitude.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • foreground : BooleanRequired

        If true, the application was foregrounded when the event occured.

      • latitude : StringRequired

        The latitude where the event occurred.

      • longitude : StringRequired

        The longitude where the event occurred.

      • session_id : String

        Represents the “session” of user activity. Absent if the application was initialized while backgrounded. Format: uuid

    • device : App Device InformationRequired

      Information about app users generated by the SDK.

    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: LOCATION

Mobile Originated Event

Example Mobile-Originated SMS Event

{
  "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d",
  "offset": "1000000701505",
  "occurred": "2018-12-03T19:31:10.000Z",
  "processed": "2018-12-03T19:31:11.302Z",
  "device": {
    "channel": "a828de17-b315-4e80-9d2d-35a906afeacf",
    "device_type": "SMS",
    "delivery_address": "15558968663"
  },
  "body": {
    "event_type": "mobile_originated_sms",
    "identifiers": {
      "sender": "15558675309",
      "msisdn": "15558968663"
    },
    "properties": {
      "inbound_message": "join",
      "outbound_message": "Thanks for joining!",
      "keyword": "join"
    }
  },
  "type": "MOBILE_ORIGINATED"
}
  • Represents a message action that originated from a user — like an inbound SMS or email.

    OBJECT PROPERTIES
    • body : ObjectRequired

      An event that occurs when a user sends a message from an SMS device, i.e., the message originates from a mobile device and not from the server (Airship). This event contains context related to the message’s origin, the incoming message itself, and Airship’s response to the origin.

      OBJECT PROPERTIES
      • event_type : StringRequired

        The specific MOBILE_ORIGINATED event that occured. Possible values: mobile_originated_sms

      • identifiers : ObjectRequired

        Contains the sender and MSISDN for the event.

        OBJECT PROPERTIES
        • msisdn : StringRequired

          The phone number of the user involved in the compliance event.

        • sender : StringRequired

          The phone number or short code of the sender involved in the compliance event.

      • properties : ObjectRequired

        Contains the mobile-originated message itself and the response to the message.

        OBJECT PROPERTIES
        • inbound_message : StringRequired

          The contents of the message received from an SMS device.

        • keyword : String

          The specific keyword used in the inbound message, if recognized; the keyword in the inbound_message determines the outbound_message sent to the device. If a keyword could not be matched in the inbound_message, this field is absent.

        • outbound_message : StringRequired

          The response sent to the SMS device, based on the inbound message and keyword.

    • device : ObjectRequired

      Holds information about an SMS “device” (an individual SMS channel).

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : String

        The phone number for the channel. Format: msisdn

      • device_type : StringRequired

        SMS compliance events list the SMS device type. Possible values: SMS

      • identifiers : Object

        If present, the identifiers object holds the value for the sender property.

        OBJECT PROPERTIES
        • sender : StringRequired

          The sender that the delivery_address received a message from.

    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: MOBILE_ORIGINATED

Open

Example Open Event

{
  "id": "910fea50-5d42-1159-b702-024288f4e1d3",
  "offset": "1000022468589",
  "occurred": "2019-04-03T18:59:02.246Z",
  "processed": "2019-04-03T19:10:26.301Z",
  "device": {
    "android_channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe",
    "channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe",
    "device_type": "ANDROID",
    "identifiers": {
      "com.urbanairship.gimbal.aii": "2471037d-71d8-4229-a40f-df719f1af914",
      "session_id": "54204a73-7a95-4ffc-8051-bf230d086e19",
      "GA_CID": "90d56c80-f31f-49fd-87b0-20deb3d2602a"
    },
    "attributes": {
      "locale_variant": "",
      "app_version": "1037.04c13d-master",
      "device_model": "Nokia 6.1",
      "connection_type": "WIFI",
      "app_package_name": "com.urbanairship.goat",
      "iana_timezone": "America/Los_Angeles",
      "push_opt_in": "true",
      "locale_country_code": "US",
      "device_os": "9",
      "locale_timezone": "-25200",
      "carrier": "Android",
      "locale_language_code": "en",
      "location_enabled": "false",
      "background_push_enabled": "true",
      "ua_sdk_version": "9.7.0",
      "location_permission": "ALWAYS_ALLOWED"
      }
    },
  "body": {
    "last_delivered": {
        "push_id": "6e3339ce-529c-42e4-a2f6-7546f81c9828",
        "time": "2015-07-30T21:03:37.631Z"
    },
    "triggering_push": {
        "push_id": "c2f6c5c5-f353-49c0-b5f7-6e87cf9b1a06",
        "group_id": "8ea2abd6-dbc7-475a-9c57-fb31c7e2999b",
        "variant_id": 1
    },
    "session_id": "ad4ad05a-17f4-4eab-9c6f-d3f7fbf3cc25"
  },
  "type": "OPEN"
}
  • Occurs when a user opens your app.

    OBJECT PROPERTIES
    • body : Object

      OBJECT PROPERTIES
      • last_delivered : Object

        Identifies the last push notification the audience received before the event. Absent if the last push occurred more than 12 hours ago.

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

          A unique identifier for a push operation. Format: uuid

        • time : String

          The UTC time when the push occurred.

        • 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).

      • session_id : String

        Represents the “session” of user activity. Absent if the application was initialized while backgrounded. Format: uuid

      • triggering_push : Object

        The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.

        An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.

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

          A unique identifier for a push operation. Format: uuid

        • time : String

          The UTC time when the push occurred.

        • 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 : App Device Information

      Information about app users generated by the SDK.

    • id : String

      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

      When the event occurred.

    • offset : String

      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

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

    • type : String

      Possible values: OPEN

Push Body

Example Push Body Event

{
  "id": "910fea50-5d42-1159-b702-024288f4e1d3",
  "offset": "1000022468589",
  "occurred": "2019-04-03T18:59:02.246Z",
  "processed": "2019-04-03T19:10:26.301Z",
  "body": {
    "push_id": "233f8109-bf56-4d95-a8bf-6f28e9d270a4",
    "campaigns": {
      "categories": [
          "hello",
          "numberwang",
          "first message"
      ]
    },
    "trimmed": false,
    "payload": "eyJkZXZpY2VfdHlwZXMiOiBbImFuZHJvaWQiLCAiaW9zIl0sICJub3RpZmljYXRpb24iOiB7ImFuZHJvaWQiOiB7fSwgImlvcyI6IHsiYmFkZ2UiOiAiKzEifSwgImFsZXJ0IjogIklUIFdJTEwgV09SSyEifSwgImF1ZGllbmNlIjogImFsbCJ9"
  },
  "type": "PUSH_BODY"
}
  • Occurs when you initiate a push, automation, or journey.

    Airship fulfills delivery over a time interval with a number of child pushes, each with a unique Push ID and a common Group ID. There is no guarantee that push body events (defined in Push Body Event) for the child pushes fulfilling a group will appear in the stream.

    Note: When you start, pause, or publish a journey, Airship emits a push_body event for the journey itself, and each message contained within the journey (i.e. messages +1). After you start a journey, Airship does not issue subsequent push_body events for the journey unless you pause or publish changes to the journey.

    OBJECT PROPERTIES
    • body : Object

      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

      • payload : StringRequired

        The specification of the push as sent via the API, a Base64 encoded JSON value.

      • push_id : String

        A unique identifier for a push operation. Format: uuid

      • resource : StringRequired

        Describes the type of push, helping you interpret the JSON response. Values pertain to the push “type”. Possible values: PIPELINES, SCHEDULES, PUSH, EXPERIMENTS

      • trimmed : BooleanRequired

        If true, the push payload was trimmed from the event body.

    • id : String

      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

      When the event occurred.

    • offset : String

      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

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

    • type : String

      Possible values: PUSH_BODY

Region Event

Example Region Event

{
  "id": "910fea50-5d42-1159-b702-024288f4e1d3",
  "offset": "1000022468589",
  "occurred": "2019-04-03T18:59:02.246Z",
  "processed": "2019-04-03T19:10:26.301Z",
  "device": {
    "android_channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe",
    "channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe",
    "device_type": "ANDROID",
    "identifiers": {
      "com.urbanairship.gimbal.aii": "2471037d-71d8-4229-a40f-df719f1af914",
      "session_id": "54204a73-7a95-4ffc-8051-bf230d086e19",
      "GA_CID": "90d56c80-f31f-49fd-87b0-20deb3d2602a"
    },
    "attributes": {
      "locale_variant": "",
      "app_version": "dev",
      "device_model": "Android SDK built for x86",
      "connection_type": "WIFI",
      "app_package_name": "com.urbanairship.goat",
      "iana_timezone": "America/Los_Angeles",
      "push_opt_in": "true",
      "locale_country_code": "US",
      "device_os": "9",
      "locale_timezone": "-25200",
      "carrier": "Android",
      "locale_language_code": "en",
      "location_enabled": "false",
      "background_push_enabled": "true",
      "ua_sdk_version": "9.7.0",
      "location_permission": "ALWAYS_ALLOWED"
    }
  },
  "body":{
    "action": "enter",
    "region_id": "fb542343-9a43-450a-be7f-43bed95057ff",
    "session_id": "0a50fdb9-dfa9-4e0e-8373-4f0c5c7137c7",
    "name": "Coolest Place",
    "source_info": {
        "source": "Gimbal",
        "region_id": "a vendor identifier"
    }
  },
  "type": "REGION"
}
  • Region Events are emitted when a device enters or exits a geofence or the range of any of a set of bluetooth beacons. Region events require a Gimbal integration. Events for Gimbal customers include the Gimbal application instance identifer as com.urbanairship.gimbal.aii within the identifiers object.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • action : StringRequired

        Indicates whether the event was the result of a user entering or exiting the region. Possible values: enter, exit

      • name : String

        A friendly name for the event; may be retrieved from a third-party.

      • region_id : StringRequired

        The identifier for the region in Airship. Format: uuid

      • session_id : String

        Represents the “session” of user activity. Absent if the application was initialized while backgrounded. Format: uuid

      • source_info : ObjectRequired

        Information about the source application that generated the event.

        OBJECT PROPERTIES
        • region_id : String

          The unique region identifier from the originating system.

        • source : String

          Identifies the system that the event originated from.

    • device : App Device InformationRequired

      Information about app users generated by the SDK.

    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: REGION

Rich Delete

Example Event Body - Indicates the push_id that was deleted

{
  "id": "ca2948b0-56ea-11e9-88dc-a142740a77e1",
  "offset": "1000022469540",
  "occurred": "2019-04-04T15:03:22.545Z",
  "processed": "2019-04-04T15:12:54.657Z",
  "device": {
    "ios_channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110",
    "channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110",
    "device_type": "IOS",
    "named_user_id": "coolusername",
    "identifiers": {
      "com.urbanairship.limited_ad_tracking_enabled": "true",
      "session_id": "837645C4-BD17-455C-96A3-999E1290EFA7",
      "GA_CID": "d12b5b66-d0c6-40f6-923f-ea039e3e8297",
      "com.urbanairship.idfa": "9610438A-6AEF-4113-BB99-2F64CB56ED2F",
      "com.urbanairship.vendor": "F2519C6C-A724-4343-80C7-1F1E42C53DFF"
    },
    "attributes": {
      "locale_variant": "",
      "app_version": "542",
      "device_model": "iPhone8,1",
      "connection_type": "CELL",
      "app_package_name": "com.urbanairship.goat",
      "iana_timezone": "Europe/London",
      "push_opt_in": "true",
      "locale_country_code": "GB",
      "device_os": "12.1.4",
      "locale_timezone": "3600",
      "carrier": "Three",
      "locale_language_code": "en",
      "location_enabled": "false",
      "background_push_enabled": "true",
      "ua_sdk_version": "10.2.0",
      "location_permission": "FOREGROUND_ALLOWED"
    }
  },
  "body": {
    "push_id": "1bf2A1a1-4069-11e9-abf1-024297609801"
  },
  "type": "RICH_DELETE"
}
  • Occurs when a user deletes a rich message from their inbox.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • 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

        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 : App Device InformationRequired

      Information about app users generated by the SDK.

    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: RICH_DELETE

Rich Delivery

Example Event Body — Indicates the push_id That reached the user

{
  "id": "83848900-54ac-11e9-a132-024278224c1c",
  "offset": "1000022466003",
  "occurred": "2019-04-01T18:32:32.912Z",
  "processed": "2019-04-01T18:32:33.031Z",
  "device": {
    "android_channel": "1de67612-94bc-4d02-85b0-37ede154a9d7",
    "channel": "1de67612-94bc-4d02-85b0-37ede154a9d7",
    "device_type": "ANDROID"
  },
  "body": {
    "push_id": "1a7d774c-1659-4104-b594-2f7ec739c92d"
  },
  "type": "RICH_DELIVERY"
}
  • Occurs when a rich message is delivered to a user’s inbox.

    Even though rich push deliveries may or may not cause an alert on the user’s lock screen, they are always associated with a push identifier in the Airship system.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • 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

        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 : App Device InformationRequired

      Information about app users generated by the SDK.

    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: RICH_DELIVERY

Rich Read

Example Event Body — Indicates the push_id that the user read

{
  "id": "ca2948b0-56ea-11e9-88dc-a142740a77e1",
  "offset": "1000022469540",
  "occurred": "2019-04-04T15:03:22.545Z",
  "processed": "2019-04-04T15:12:54.657Z",
  "device": {
    "ios_channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110",
    "channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110",
    "device_type": "IOS",
    "named_user_id": "coolusername",
    "identifiers": {
      "com.urbanairship.limited_ad_tracking_enabled": "true",
      "session_id": "837645C4-BD17-455C-96A3-999E1290EFA7",
      "GA_CID": "d12b5b66-d0c6-40f6-923f-ea039e3e8297",
      "com.urbanairship.idfa": "9610438A-6AEF-4113-BB99-2F64CB56ED2F",
      "com.urbanairship.vendor": "F2519C6C-A724-4343-80C7-1F1E42C53DFF"
    },
    "attributes": {
      "locale_variant": "",
      "app_version": "542",
      "device_model": "iPhone8,1",
      "connection_type": "CELL",
      "app_package_name": "com.urbanairship.goat",
      "iana_timezone": "Europe/London",
      "push_opt_in": "true",
      "locale_country_code": "GB",
      "device_os": "12.1.4",
      "locale_timezone": "3600",
      "carrier": "Three",
      "locale_language_code": "en",
      "location_enabled": "false",
      "background_push_enabled": "true",
      "ua_sdk_version": "10.2.0",
      "location_permission": "FOREGROUND_ALLOWED"
    }
  },
  "body": {
    "push_id": "1bf2A1a1-4069-11e9-abf1-024297609801"
    "time": "2019-03-04T15:12:54.657Z"
  },
  "type": "RICH_READ"
}
  • Occurs when a user reads a rich message in their inbox.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • 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

        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 : App Device InformationRequired

      Information about app users generated by the SDK.

    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: RICH_READ

Screen Viewed

Example SMS Create-and-Send Event

{
  "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d",
  "offset": "1000000701505",
  "occurred": "2018-12-03T19:31:10.000Z",
  "processed": "2018-12-03T19:31:11.302Z",
  "device": {
    "ios_channel": "c1ca5af6-b014-46f9-8566-33f5f52c7b19",
    "channel": "c9cb18f7-b814-40f9-8566-33f5f52c7c48",
    "device_type": "IOS",
    "identifiers": {
      "com.urbanairship.limited_ad_tracking_enabled": "true",
      "session_id": "B1E00276-98BE-4B38-9077-FB2E90EFBE1B",
      "GA_CID": "1fa021e7-8298-4f92-bee0-07cb95eecfdd",
      "com.urbanairship.idfa": "1821a235-CD43-4ED8-8633-3BD3B991FA25",
      "com.urbanairship.vendor": "164d552C-F5F0-4C83-B529-321667C8E48A"
    },
    "attributes": {
      "locale_variant": "",
      "app_version": "550",
      "device_model": "iPhone9,1",
      "connection_type": "WIFI",
      "app_package_name": "com.urbanairship.goat",
      "iana_timezone": "Europe/Berlin",
      "push_opt_in": "true",
      "locale_country_code": "US",
      "device_os": "12.2",
      "locale_timezone": "7200",
      "locale_language_code": "en",
      "location_enabled": "false",
      "background_push_enabled": "true",
      "ua_sdk_version": "10.2.2",
      "location_permission": "FOREGROUND_ALLOWED"
    }
  },
  "body": {
    "duration": 13933,
    "viewed_screen": "home",
    "previous_screen": "message_center",
    "session_id": "a26102f9-7fb2-451d-a65c-56e9394cf726"
  },
  "type": "SCREEN_VIEWED"
}
  • Occurs when a user has finished viewing a screen. It is up to you to instrument your application with names for each screen. Doing so will allow you to deterimine the user’s path by filtering on the fields in the table below.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • duration : Integer

        The number of milliseconds that the user was on the screen.

      • previous_screen : String

        The name assigned to the screen the user was on prior to the viewed_screen.

      • session_id : String

        Represents the “session” of user activity. Absent if the application was initialized while backgrounded. Format: uuid

      • viewed_screen : String

        The name assigned to the screen that the user left.

    • device : App Device InformationRequired

      Information about app users generated by the SDK.

    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: SCREEN_VIEWED

Send

Example Send Event

{
  "id": "ca2948b0-56ea-11e9-88dc-a142740a77e1",
  "offset": "1000022469540",
  "occurred": "2019-04-04T15:03:22.545Z",
  "processed": "2019-04-04T15:12:54.657Z",
  "device": {
    "ios_channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110",
    "channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110",
    "device_type": "IOS",
    "named_user_id": "coolusername",
    "attributes": {
      "locale_variant": "",
      "app_version": "542",
      "device_model": "iPhone8,1",
      "connection_type": "CELL",
      "app_package_name": "com.urbanairship.goat",
      "iana_timezone": "Europe/London",
      "push_opt_in": "true",
      "locale_country_code": "GB",
      "device_os": "12.1.4",
      "locale_timezone": "3600",
      "carrier": "Three",
      "locale_language_code": "en",
      "location_enabled": "false",
      "background_push_enabled": "true",
      "ua_sdk_version": "10.2.0",
      "location_permission": "FOREGROUND_ALLOWED"
    }
  },
  "body": {
    "variant_id": 1,
    "push_id": "0c173744-dd35-4b5e-9f7f-2b7e0ce0e36e",
    "alerting": true,
    "campaigns": {
        "categories": [
          "hello",
          "numberwang",
          "first message"
        ]
      }
    },
  "type": "SEND"
}
  • Occurs whenever a push notification is sent to a device identified in the audience selector of a message.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • alerting : Boolean

        If true, the send event was alerting. Alerting send event has notification text, badge, or sound.

      • 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 : StringRequired

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

      One of
    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: SEND

Send Aborted

Example SEND_ABORTED Event

{
  "id": "fc06bf54-619b-4fda-9345-d8f9f8e891ef",
  "occurred": "2021-02-26T20:50:21.12Z",
  "offset": "1000001215643",
  "processed": "2021-02-26T20:50:49.64Z",
  "type": "SEND_ABORTED",
  "device": {
    "android_channel": "e664fb42-d1a7-4956-9907-88c49394ae70",
    "channel": "e664fb42-d1a7-4956-9907-88c49394ae70",
    "device_type": "ANDROID",
    },
  "body": {
    "push_id": "26ea5408-a1ec-4771-b4f0-e86d45c03f8a",
    "group_id": "3795a26d-2d74-462b-b228-ca3ed31ef7b1",
    "reason": "FEED_RESOLVE_FAILURE"
  }
}
  • Occurs when a push is dropped from our system before delivery is attempted. This can happen if you are using External Data Feeds to personalize a message and an error was encountered or the feed returned a non-successful response, or when reaching a Message Limit.

    Device information for the device that did not receive the push is included with SEND_ABORTED events.

    OBJECT PROPERTIES
    • body : ObjectRequired

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

        A unique identifier for a push operation. Format: uuid

      • reason : StringRequired

        Describes the reason this push was aborted. Possible values: FEED_RESOLVE_FAILURE, FEED_REQUEST_REJECTED, FREQUENCY_LIMIT_REACHED, UNKNOWN

    • device : App Device InformationRequired

      Information about app users generated by the SDK.

    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: SEND_ABORTED

Send Rejected

Example SEND_REJECTED Event Body

{
  "id": "00000169-4a14-67b2-1ddd-d9e733622c3a",
  "occurred": "2019-03-04T19:00:45.106Z",
  "offset": "1000001260057",
  "processed": "2019-03-04T19:00:47.094Z",
  "type": "SEND_REJECTED",
  "device": {
    "ios_channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110",
    "channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110",
    "device_type": "IOS",
    },
  "body": {
    "variant_id": 1,
    "push_id": "0c173744-dd35-4b5e-9f7f-2b7e0ce0e36e",
    "campaigns" : {
      "categories" : ["hello", "first message"]
    }
  }
}
  • Occurs when a push fails during communication with a third party, like APNS or GCM. This typically indicates that the user has uninstalled the app or otherwise invalidated the last-registered credentials stored in Airship. The event contains the rejected push and the group, variant, or campaigns the push belonged to.

    Device information for the device that did not receive the push is included with SEND_REJECTED events.

    OBJECT PROPERTIES
    • body : ObjectRequired

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

        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 : App Device InformationRequired

      Information about app users generated by the SDK.

    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: SEND_REJECTED

Example short_link_click Event

{
    "id": "31549b7d-a435-4b04-abca-69bfd4fb6aaa",
    "offset": "1000005313850",
    "occurred": "2019-07-10T23:18:57.465Z",
    "processed": "2019-07-10T23:18:58.148Z",
    "device": {
        "channel": "ec71312b-42e4-4bcd-b742-581a84941793",
        "device_type": "SMS",
        "delivery_address": "15551234567",
        "identifiers": {
            "sender": "15558647425"
        },
        "attributes": {
            "web_user_agent_string": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/75.0.3770.100 Safari\/537.36"
        }
    },
    "body": {
        "push_id": "f4b4201a-70e2-4a8d-bc8f-f35ddfa7d0e7",
        "group_id": "47f01bbf-2efa-4743-acd8-fd1023a36744",
        "properties": {
          "original_url": "https://docs.airship.com/api/connect#schemas-short_link_click"
        }
    },
    "type": "SHORT_LINK_CLICK"
}
  • Occurs when a user taps or “clicks” an Airship-shortened link in an SMS or MMS message.

    OBJECT PROPERTIES
    • body : ObjectRequired

      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

      • properties : ObjectRequired

        OBJECT PROPERTIES
        • original_url : StringRequired

          The URL represented by the Airship-shortened link.

      • push_id : StringRequired

        A unique identifier for a push operation. Format: uuid

    • device : ObjectRequired

      OBJECT PROPERTIES
      • attributes : Object

        OBJECT PROPERTIES
        • web_user_agent_string : String

          Describes the web user agent for the audience member who used the link.

      • channel : StringRequired

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

      • delivery_address : String

        The MSISDN of the audience member who clicked the link.

      • device_type : StringRequired

        Possible values: SMS

      • identifiers : Object

        OBJECT PROPERTIES
        • sender : StringRequired

          The sender of the message.

    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: SHORT_LINK_CLICK

Subscription Event

Example Subscription Event

{
  "id": "62f3b7ac-4048-4f22-a0b5-22c01ef172a9",
  "offset": "1000022265027",
  "occurred": "2019-04-01T13:00:23.186Z",
  "processed": "2019-04-01T13:00:23.456Z",
  "device": {
    "channel": "6b46c724-494b-4491-9fe7-1b903d266110",
    "device_type": "EMAIL",
    "delivery_address": "user+43679@urbanairship.com.sink.sparkpostmail.com"
  },
  "body": {
    "event_type":"registration",
    "identifiers": {
      "address":"new.subscription@emaildomain.com"
    },
    "properties":{
      "commercial_opted_in":"2019-01-04T20:56:00.000Z",
      "transactional_opted_in":"2019-01-04T20:56:00.000Z"
      }
  },
  "type": "SUBSCRIPTION"
}
  • SUBSCRIPTION events reflect changes to users' subscription preferences — reflected in opt_in and opt_out values. These events help you track a user’s subscription status in the system and the total number of subscribers.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • event_type : StringRequired

        Determines the source of the subscription event. registration and create_and_send events result in changes to opted_in dates; all other event types contain opted_out dates.

        • registration: Represents a change to a user’s commercial_opted_in or transactional_opted_in dates. Either a user joined a list or updated their status for a list.
        • create_and_send: A user’s opted_in status changed as a result of a create-and-send event.
        • bounce: Subscription status changed as a result of a bounce event.
        • list_unsubscribe: The user clicked the unsubscribe button in their email client.
        • link_unsubscribe: The user clicked an unsubscribe hyperlink in an email.
        • spam_complaint: The user classified an email as spam.
        • out_of_band: A bounce occured after the recipient MTA accepted an email.

        Possible values: registration

      • identifiers : ObjectRequired

        Contains address information specific to the channel_id specified in the event.

        OBJECT PROPERTIES
        • address : String

          The email address representing the change.

    • device : ObjectRequired

      Holds information about the email “device” (an individual email channel) the event occurred against.

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : StringRequired

        The email address of the channel the event occured against.

      • device_type : StringRequired

        email compliance events use the EMAIL device type. Possible values: EMAIL

      • named_user : String

        The named user that the channel is associated with; appears only if the channel is associated with a named user.

    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: SUBSCRIPTION

Tag Change

Example Tag Change Event

{
  "id": "00000169-4a14-67b2-1ddd-d9e733622c3a",
  "occurred": "2019-03-04T19:00:45.106Z",
  "offset": "1000001260057",
  "processed": "2019-03-04T19:00:47.094Z",
  "type": "SEND_REJECTED",
  "device": {
    "ios_channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110",
    "channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110",
    "device_type": "IOS",
    },
  "body":{
    "add": {
        "crm": [
          "partner",
          "active"
        ],
        "loyalty": [
          "silver_member"
        ]
    },
    "remove": {
        "device": [
          "shoe_buyer"
        ]
    },
    "current": {
        "crm": [
          "partner",
          "active",
          "new_user"
        ],
        "loyalty": [
          "silver_member",
          "special_offers"
        ],
        "device": [
          "san_francisco",
          "sports"
        ]
      }
    },
  "type": "TAG_CHANGE"
}
  • Occurs when tags change for a device.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • add : Object

        Tag group/tag pairs added to the device. Each tag group is an array containing one or more tags within this object.

      • current : Object

        The total set/state of tag group/tag pairs associated with the device after the tag change. Each tag group is an array containing one or more tags within this object.

      • remove : Object

        Tag group/tag pairs removed from the device. Each tag group is an array containing one or more tags within this object.

    • device : AnyRequired

      One of
      • App Device Information

        Information about app users generated by the SDK.

      • Web Device Information without `attributes` : Object

        Information about web users in tag change events.

        OBJECT PROPERTIES
        • channel : StringRequired

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

        • device_type : StringRequired

          The platform that the channel is on. Possible values: WEB

        • named_user_id : String

          the named user identifier for the device.

      • Device Information for SMS and Email

        Information about the SMS or Email device related to an event.

      • Open Channel Device Information

        Information about open channel users.

    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: TAG_CHANGE

Uninstall

Example Uninstall Event

{
  "id": "00000169-4a14-67b2-1ddd-d9e733622c3a",
  "occurred": "2019-03-04T19:00:45.106Z",
  "offset": "1000001260057",
  "processed": "2019-03-04T19:00:47.094Z",
  "type": "UNINSTALL",
  "device": {
    "ios_channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110",
    "channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110",
    "device_type": "IOS",
    },
  "body":{
    "decay": false
    }
  "type": "UNINSTALL"
}
  • Occurs when a user uninstalls an Airship-integrated app in response to a push.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • decay : BooleanRequired

        If true, Airship recorded an uninstall event due to user inactivity.

    • device : AnyRequired

      One of
    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: UNINSTALL

Web Click Event

Example Web Click Event

{
  "id": "c91efbfa-14b1-401a-9002-54730b5cdcda",
  "offset": "1000024775634",
  "occurred": "2019-04-05T20:11:36.696Z",
  "processed": "2019-04-05T20:11:37.179Z",
  "device": {
    "channel": "bd054c5b-d614-46a1-a843-6ca330c66489",
    "device_type": "WEB",
    "attributes": {
      "web_browser_type": "desktop",
      "push_opt_in": "true",
      "iana_timezone": "America/Los_Angeles",
      "locale_country_code": "US",
      "locale_timezone": "-25200",
      "web_browser_version": "chrome-73",
      "locale_language_code": "en",
      "web_browser_name": "chrome",
      "ua_sdk_version": "1.1.0",
      "web_user_agent_string": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.86 Safari/537.36"
    }
  },
  "body": {
    "push_id": "c2f6c5c5-f353-49c0-b5f7-6e87cf9b1a06"
  },
  "type": "WEB_CLICK"
}
  • Occurs when user interacts with a web notification, e.g. clicked on or tapped it. Web Click events have a device attribute on the event indicating the channel that was the target of the notification. The body of a Web Click Event is an Associated Push object.

    OBJECT PROPERTIES
    • body : ObjectRequired

      The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.

      An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.

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

        A unique identifier for a push operation. Format: uuid

      • time : String

        The UTC time when the push occurred.

      • 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 : ObjectRequired

      Information about web users generated by the SDK.

      OBJECT PROPERTIES
      • attributes : Object

        OBJECT PROPERTIES
        • iana_timezone : String

          The time zone of the device.

        • push_opt_in : StringRequired

          Indicates whether or not the device is opted into push notifications.

        • ua_sdk_version : StringRequired

          The version of the Airship SDK used in the app.

        • web_browser_name : StringRequired

          The name of the browser running the SDK.

        • web_browser_type : StringRequired

          Indicates whether the browser was running on a desktop or mobile device.

        • web_browser_version : StringRequired

          The version of the browser.

        • web_user_agent_string : StringRequired

          The user agent reported by the browser.

      • channel : StringRequired

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

      • device_type : StringRequired

        The platform that the channel is on. Possible values: WEB

      • named_user_id : String

        the named user identifier for the device.

    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: WEB_CLICK

Web Session Event

Example Web Session Event

{
  "id": "c91efbfa-14b1-401a-9002-54730b5cdcda",
  "offset": "1000024775634",
  "occurred": "2019-04-05T20:11:36.696Z",
  "processed": "2019-04-05T20:11:37.179Z",
  "device": {
    "channel": "bd054c5b-d614-46a1-a843-6ca330c66489",
    "device_type": "WEB",
    "attributes": {
      "web_browser_type": "desktop",
      "push_opt_in": "true",
      "iana_timezone": "America/Los_Angeles",
      "locale_country_code": "US",
      "locale_timezone": "-25200",
      "web_browser_version": "chrome-73",
      "locale_language_code": "en",
      "web_browser_name": "chrome",
      "ua_sdk_version": "1.1.0",
      "web_user_agent_string": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.86 Safari/537.36"
    }
  },
  "body": {
    "session_id": "e8350094-dd62-4d36-a7a0-f1b0a221de93",
    "last_delivered": {
        "push_id": "c2f6c5c5-f353-49c0-b5f7-6e87cf9b1a06"
      }
    },
  "type": "WEB_SESSION"
}
  • Occurs when an opted in user begins interacting with a website. Web Session events have a device attribute, indicating the channel associated with the user.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • last_delivered : Object

        Identifies the last push notification the audience received before the event. Absent if the last push occurred more than 12 hours ago.

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

          A unique identifier for a push operation. Format: uuid

        • time : String

          The UTC time when the push occurred.

        • 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).

      • session_id : String

        Represents the “session” of user activity. Absent if the application was initialized while backgrounded. Format: uuid

      • triggering_push : Object

        The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.

        An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.

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

          A unique identifier for a push operation. Format: uuid

        • time : String

          The UTC time when the push occurred.

        • 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 : Web Device InformationRequired

      Information about web users generated by the SDK.

    • id : StringRequired

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

      When the event occurred.

    • offset : String

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

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

    • type : StringRequired

      Possible values: WEB_SESSION

Email Compliance Events

Contains event body information specific to email compliance events.

Email Bounce Event

Example Email Bounce Event

{
    "id": "9781ff2e-fa4a-4fa8-bd9d-41f318c48963",
    "offset": "1000001778910",
    "occurred": "2018-11-28T00:02:41.794Z",
    "processed": "2018-11-28T00:02:45.270Z",
    "device": {
        "channel": "5a39b6d8-0a5a-4c2b-a4a0-3d4a71e5254b",
        "device_type": "EMAIL",
        "delivery_address": "bademail@baddomain.com"
    },
    "body": {
        "event_type": "bounce",
        "properties": {
            "bounce_event_type": "bounce",
            "sender": "msprvs1=17870ayYKWpBI=bounces-179492-4@spmailtechnolo.com",
            "subject": "Red Means Go",
            "email": "bademail@baddomain.com",
            "bounce_class": "10"
        }
    },
    "type": "COMPLIANCE"
}
  • An event that occurs when an email could not be delivered to a particular address. The bounce_class can provide more information about why the message bounced.

    OBJECT PROPERTIES
    • body : ObjectRequired

      Contains the event subtype and additional properties about the event.

      OBJECT PROPERTIES
      • event_type : StringRequired

        Possible values: bounce

      • identifiers : ObjectRequired

        OBJECT PROPERTIES
        • address : String

          The email address registered.

      • properties : ObjectRequired

        OBJECT PROPERTIES
        • bounce_class : Integer

          The bounce classifcation as specified in Sparkpost. Max: 100 Min: 1

        • bounce_event_type : String

          Possible values: bounce

        • email : String

          The email address that bounced. Format: email

        • sender : String

          The address that the bounced email came from (typically the sender address for your project in Airship).

        • subject : String

          The subject line of the bounced email.

    • device : ObjectRequired

      Holds information about the email “device” (an individual email channel) the event occurred against.

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : StringRequired

        The email address of the channel the event occured against.

      • device_type : StringRequired

        email compliance events use the EMAIL device type. Possible values: EMAIL

      • named_user : String

        The named user that the channel is associated with; appears only if the channel is associated with a named user.

Email Create-and-Send Event Body

Example Email create_and_send Event

{
    "id": "adf8794c-c3c3-4507-9ea3-1a554ed4b94f",
    "offset": "1000001778141",
    "occurred": "2018-11-27T23:20:12.167Z",
    "processed": "2018-11-27T23:20:12.443Z",
    "device": {
        "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
        "device_type": "EMAIL",
        "delivery_address": "new.address@subscriber.com"
    },
    "body": {
        "event_type": "create_and_send",
        "identifiers": {
            "address": "new.address@subscriber.com.com"
        },
        "properties": {
            "channel_registered": "true",
            "commercial_opted_in": "2018-10-12T12:12:12"
        }
    },
    "type": "COMPLIANCE"
  }
  • An event that occurs for email addresses used as a part of a create-and-send message.

    OBJECT PROPERTIES
    • body : ObjectRequired

      Contains the event subtype and additional properties about the event.

      OBJECT PROPERTIES
      • event_type : StringRequired

        Possible values: create_and_send

      • identifiers : ObjectRequired

        OBJECT PROPERTIES
        • address : StringRequired

          The email address a message was sent to using the create-and-send (inline list) feature.

      • properties : ObjectRequired

        Properties for an email create-and-send event.

        OBJECT PROPERTIES
        • channel_registered : BooleanRequired

          If true, a new channel was created to represent the identifiers in the event. If false, the address was already registered to Airship.

        • commercial_opted_in : String

          The date and time when the address opted into commercial email messages.

        • transactional_opted_in : String

          The date and time when the address opted into transactional email messages.

    • device : ObjectRequired

      Holds information about the email “device” (an individual email channel) the event occurred against.

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : StringRequired

        The email address of the channel the event occured against.

      • device_type : StringRequired

        email compliance events use the EMAIL device type. Possible values: EMAIL

      • named_user : String

        The named user that the channel is associated with; appears only if the channel is associated with a named user.

Email Registration Event

Example Email Registration Event

{
    "id": "8058bfd3-9081-4f48-845c-809bf5462ca4",
    "offset": "1000000739139",
    "occurred": "2018-12-18T21:24:11.836Z",
    "processed": "2018-12-18T21:24:12.608Z",
    "device": {
        "channel": "93f32fb8-0e40-440b-8944-2f9ef933ca88",
        "device_type": "EMAIL"
    },
    "body": {
        "event_type": "registration",
        "identifiers": {
            "address": "new.user@subscriber.com"
        },
        "properties": {
            "commercial_opted_in": "2018-10-20T12:00:00.000Z",
            "registration_type": "create"
        }
    },
    "type": "COMPLIANCE"
  }
  • An event that occurs when users register to receive email messages.

    OBJECT PROPERTIES
    • body : ObjectRequired

      Contains the event subtype and additional properties about the event.

      OBJECT PROPERTIES
      • event_type : StringRequired

        Possible values: registration

      • identifiers : ObjectRequired

        OBJECT PROPERTIES
        • address : String

          The email address registered.

      • properties : ObjectRequired

        OBJECT PROPERTIES
        • commercial_opted_in : String

          The date and time when the user opted into commercial email messages.

        • registration_type : StringRequired

          create indicates that a channel was created in Airship. update represents a PUT call to the email channel registration API.

          Possible values: create, update

    • device : ObjectRequired

      Holds information about the email “device” (an individual email channel) the event occurred against.

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : StringRequired

        The email address of the channel the event occured against.

      • device_type : StringRequired

        email compliance events use the EMAIL device type. Possible values: EMAIL

      • named_user : String

        The named user that the channel is associated with; appears only if the channel is associated with a named user.

Email Unsubscribe Event

Example Email Unsubscribe Event

{
  "id": "bd8c90d6-5704-4438-8075-7530d06c4cba",
  "offset": "1000001778792",
  "occurred": "2018-11-27T23:47:54.641Z",
  "processed": "2018-11-27T23:47:55.516Z",
  "device": {
      "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
      "device_type": "EMAIL",
      "delivery_address": "former.user@unsubscriber.com"
  },
  "body": {
      "event_type": "registration",
      "properties": {
          "message_type": "commercial",
          "registration_type": "unsubscribe"
      }
  },
  "type": "COMPLIANCE"
}
  • A compliance event representing a user who unsubscribed from your email notifications.

    OBJECT PROPERTIES
    • body : ObjectRequired

      Contains the event subtype and additional properties about the event.

      OBJECT PROPERTIES
      • event_type : StringRequired

        Unsubscribe events are considered “registration” events; the “registration_type” indicates the type of registration occurring. Possible values: registration

      • identifiers : ObjectRequired

        OBJECT PROPERTIES
        • address : String

          The email address registered.

      • properties : ObjectRequired

        OBJECT PROPERTIES
        • message_type : StringRequired

          The message type that the user unsubscribed from. Possible values: commercial

        • registration_type : StringRequired

          Possible values: unsubscribe

    • device : ObjectRequired

      Holds information about the email “device” (an individual email channel) the event occurred against.

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : StringRequired

        The email address of the channel the event occured against.

      • device_type : StringRequired

        email compliance events use the EMAIL device type. Possible values: EMAIL

      • named_user : String

        The named user that the channel is associated with; appears only if the channel is associated with a named user.

SMS Compliance Events

Contains event body information specific to SMS compliance events.

SMS API Initiated Opt In Event

Example API-initiated Opt-In Event

{
    "id": "a11d6d6b-bdd1-4f3d-97d3-591993945425",
    "offset": "1000005312986",
    "occurred": "2019-07-10T17:11:48.923Z",
    "processed": "2019-07-10T17:11:49.151Z",
    "device": {
        "channel": "35eb0446-0c75-44ec-ba9e-81d7250e0e06",
        "device_type": "SMS"
    },
    "body": {
        "event_type": "api_initiate_opt_in",
        "identifiers": {
            "sender": "18338647425",
            "msisdn": "15035508427"
        }
    },
    "type": "COMPLIANCE"
}
  • Occurs when an SMS user is registered via the SMS Channel Registration API without an opted_in value — indicating that the user has initiated, but not completed, the registration process. While this event contains a channel_id, you cannot send messages to this channel until the associated user completes the opt-in process (indicated by a mobile_opt_in event).

    OBJECT PROPERTIES
    • body : ObjectRequired

      Contains the event subtype, identifiers, and additional properties about the event.

      OBJECT PROPERTIES
      • event_type : StringRequired

        Indicates a registration was started via the Airship API without an opt-in date, and a message was sent to the end user with instructions on how to opt in.

        Possible values: api_initiate_opt_in

      • identifiers : ObjectRequired

        Contains the sender and MSISDN for the event.

        OBJECT PROPERTIES
        • msisdn : StringRequired

          The phone number of the user involved in the compliance event.

        • sender : StringRequired

          The phone number or short code of the sender involved in the compliance event.

    • device : ObjectRequired

      Holds information about an SMS “device” (an individual SMS channel).

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : String

        The phone number for the channel. Format: msisdn

      • device_type : StringRequired

        SMS compliance events list the SMS device type. Possible values: SMS

      • identifiers : Object

        If present, the identifiers object holds the value for the sender property.

        OBJECT PROPERTIES
        • sender : StringRequired

          The sender that the delivery_address received a message from.

SMS Carrier Deactivation Event

Example SMS carrier_deactivation Event

{
  "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d",
  "offset": "1000000701505",
  "occurred": "2018-12-03T19:31:10.000Z",
  "processed": "2018-12-03T19:31:11.302Z",
  "device": {
    "channel": "a828de17-b315-4e80-9d2d-35a906afeacf",
    "device_type": "SMS",
    "delivery_address": "15558968663"
  },
  "body": {
    "event_type": "carrier_deactivation",
    "identifiers": {
      "sender": "15558675309",
      "msisdn": "15558968663"
    }
  },
  "type": "COMPLIANCE"
}
  • Occurs when an MSISDN is deactivated by a carrier. This event type does not contain additional properties.

    OBJECT PROPERTIES
    • body : ObjectRequired

      Contains the event subtype, identifiers, and additional properties about the event.

      OBJECT PROPERTIES
      • event_type : StringRequired

        The carrier deactivated the address. Possible values: carrier_deactivation

      • identifiers : ObjectRequired

        Contains the sender and MSISDN for the event.

        OBJECT PROPERTIES
        • msisdn : StringRequired

          The phone number of the user involved in the compliance event.

        • sender : StringRequired

          The phone number or short code of the sender involved in the compliance event.

SMS Custom Keyword Response Event

Example Custom Keyword Response Event

{
    "id": "34464823-b48c-4ed3-8849-03933f29d057",
    "offset": "1000005313855",
    "occurred": "2019-07-11T00:24:39.203Z",
    "processed": "2019-07-11T00:24:40.128Z",
    "device": {
        "channel": "ec71312b-42e4-4bcd-b742-581a84941793",
        "device_type": "SMS",
        "delivery_address": "15035508427",
        "identifiers": {
            "sender": "18338647425"
        }
    },
    "body": {
        "event_type": "custom_keyword_response",
        "identifiers": {
            "sender": "18338647425",
            "msisdn": "15035508427"
        },
        "properties": {
            "inbound_message": "coupon",
            "outbound_message": "Thanks! Here is your coupon! https:\/\/wallet-api.urbanairship.com\/v1\/pass\/adaptive\/M1kTVOcyXm"
        }
    },
    "type": "COMPLIANCE"
}
  • Occurs when a mobile-originated keyword is matched, and elicits a custom response.

    OBJECT PROPERTIES
    • body : ObjectRequired

      Contains the event subtype, identifiers, and additional properties about the event.

      OBJECT PROPERTIES
      • event_type : StringRequired

        Occurs when a mobile-originated keyword generates a custom response. Possible values: custom_keyword_response

      • identifiers : ObjectRequired

        Contains the sender and MSISDN for the event.

        OBJECT PROPERTIES
        • msisdn : StringRequired

          The phone number of the user involved in the compliance event.

        • sender : StringRequired

          The phone number or short code of the sender involved in the compliance event.

      • properties : ObjectRequired

        Contains properties specific to the event_type.

        OBJECT PROPERTIES
        • inbound_message : String

          The body of the inbound (to Airship) text message. This is the message a user sent to opt into or out of messages. This text corresponds to the keyword if present.

        • outbound_message : String

          The message you sent to the user represented in the event.

    • device : ObjectRequired

      Holds information about an SMS “device” (an individual SMS channel).

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : String

        The phone number for the channel. Format: msisdn

      • device_type : StringRequired

        SMS compliance events list the SMS device type. Possible values: SMS

      • identifiers : Object

        If present, the identifiers object holds the value for the sender property.

        OBJECT PROPERTIES
        • sender : StringRequired

          The sender that the delivery_address received a message from.

SMS Mobile Create Channel Event

Example SMS mobile_create_channel Event

{
  "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d",
  "offset": "1000000701505",
  "occurred": "2018-12-03T19:31:10.000Z",
  "processed": "2018-12-03T19:31:11.302Z",
  "device": {
    "channel": "a828de17-b315-4e80-9d2d-35a906afeacf",
    "device_type": "SMS",
    "delivery_address": "15558968663"
  },
  "body": {
    "event_type": "mobile_create_channel",
    "identifiers": {
      "sender": "15558675309",
      "msisdn": "15558968663"
    },
    "properties": {
      "inbound_message": "JOIN",
      "outbound_message": "Your order number is #123456789. Text 'JOIN' to learn about new offers from us.",
      "keyword": "JOIN"
    }
  },
  "type": "COMPLIANCE"
}
  • If a channel does not exist for the MSISDN/sender combination and your account is configured to create a channel if none exists in such instances, we will emit this event. The resulting channel will necessarily be opted out, awaiting an opt-in action by the user.

    OBJECT PROPERTIES
    • body : ObjectRequired

      Contains the event subtype, identifiers, and additional properties about the event.

      OBJECT PROPERTIES
      • event_type : StringRequired

        Indicates that a channel for the sms event type was created. Possible values: mobile_create_channel

      • identifiers : ObjectRequired

        Contains the sender and MSISDN for the event.

        OBJECT PROPERTIES
        • msisdn : StringRequired

          The phone number of the user involved in the compliance event.

        • sender : StringRequired

          The phone number or short code of the sender involved in the compliance event.

      • properties : ObjectRequired

        Contains properties specific to the event_type.

        OBJECT PROPERTIES
        • opted_in : String

          The date and time when the channel was registered.

        • registration_type : String

          Indicates that the channel was registered with Airship. Possible values: create

    • device : ObjectRequired

      Holds information about an SMS “device” (an individual SMS channel).

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : String

        The phone number for the channel. Format: msisdn

      • device_type : StringRequired

        SMS compliance events list the SMS device type. Possible values: SMS

      • identifiers : Object

        If present, the identifiers object holds the value for the sender property.

        OBJECT PROPERTIES
        • sender : StringRequired

          The sender that the delivery_address received a message from.

SMS Mobile Keyword Matched Event

Example SMS mobile_keyword_matched Event

{
  "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d",
  "offset": "1000000701505",
  "occurred": "2018-12-03T19:31:10.000Z",
  "processed": "2018-12-03T19:31:11.302Z",
  "device": {
    "channel": "a828de17-b315-4e80-9d2d-35a906afeacf",
    "device_type": "SMS",
    "delivery_address": "15558968663"
  },
  "body": {
    "event_type": "mobile_keyword_matched",
    "identifiers": {
      "sender": "15558675309",
      "msisdn": "15558968663"
    },
    "properties": {
      "inbound_message": "join",
      "outbound_message": "Wanna join the club?",
      "keyword": "JOIN"
    }
  },
  "type": "COMPLIANCE"
}
  • Occurs when a mobile-originated message contains a recognized keyword.

    OBJECT PROPERTIES
    • body : ObjectRequired

      Contains the event subtype, identifiers, and additional properties about the event.

      OBJECT PROPERTIES
      • event_type : StringRequired

        Occurs when a mobile-originated event contains a recognized keyword. Possible values: mobile_keyword_matched

      • identifiers : ObjectRequired

        Contains the sender and MSISDN for the event.

        OBJECT PROPERTIES
        • msisdn : StringRequired

          The phone number of the user involved in the compliance event.

        • sender : StringRequired

          The phone number or short code of the sender involved in the compliance event.

      • properties : ObjectRequired

        Contains properties specific to the event_type.

        OBJECT PROPERTIES
        • inbound_message : String

          The body of the inbound (to Airship) text message. This is the message a user sent to opt into or out of messages. This text corresponds to the keyword if present.

        • keyword : String

          Indicates that a mobile-originated message contained a recognized keyword.

        • outbound_message : String

          The message you sent to the user represented in the event.

    • device : ObjectRequired

      Holds information about an SMS “device” (an individual SMS channel).

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : String

        The phone number for the channel. Format: msisdn

      • device_type : StringRequired

        SMS compliance events list the SMS device type. Possible values: SMS

      • identifiers : Object

        If present, the identifiers object holds the value for the sender property.

        OBJECT PROPERTIES
        • sender : StringRequired

          The sender that the delivery_address received a message from.

SMS Mobile Keyword Unmatched Event

Example SMS mobile_keyword_unmatched Event

{
  "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d",
  "offset": "1000000701505",
  "occurred": "2018-12-03T19:31:10.000Z",
  "processed": "2018-12-03T19:31:11.302Z",
  "device": {
    "channel": "a828de17-b315-4e80-9d2d-35a906afeacf",
    "device_type": "SMS",
    "delivery_address": "15558968663"
  },
  "body": {
    "event_type": "mobile_keyword_unmatched",
    "identifiers": {
      "sender": "15558675309",
      "msisdn": "15558968663"
    },
    "properties": {
      "inbound_message": "@%#!&@&#",
      "outbound_message": "Wanna join the club?"
    }
  },
  "type": "COMPLIANCE"
}
  • Occurs when a mobile-originated message does not contain a recognized keyword.

    OBJECT PROPERTIES
    • body : ObjectRequired

      Contains the event subtype, identifiers, and additional properties about the event.

      OBJECT PROPERTIES
      • event_type : StringRequired

        Occurs when a mobile-originated event does not contain a recognized keyword. Possible values: mobile_keyword_unmatched

      • identifiers : ObjectRequired

        Contains the sender and MSISDN for the event.

        OBJECT PROPERTIES
        • msisdn : StringRequired

          The phone number of the user involved in the compliance event.

        • sender : StringRequired

          The phone number or short code of the sender involved in the compliance event.

      • properties : ObjectRequired

        Contains properties specific to the event_type.

        OBJECT PROPERTIES
        • inbound_message : String

          The body of the inbound (to Airship) text message. This is the message a user sent to opt into or out of messages. This text corresponds to the keyword if present.

        • outbound_message : String

          The message you sent to the user represented in the event.

    • device : ObjectRequired

      Holds information about an SMS “device” (an individual SMS channel).

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : String

        The phone number for the channel. Format: msisdn

      • device_type : StringRequired

        SMS compliance events list the SMS device type. Possible values: SMS

      • identifiers : Object

        If present, the identifiers object holds the value for the sender property.

        OBJECT PROPERTIES
        • sender : StringRequired

          The sender that the delivery_address received a message from.

SMS Mobile Opt In Event

Example SMS mobile_opt_in Event

{
  "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d",
  "offset": "1000000701505",
  "occurred": "2018-12-03T19:31:10.000Z",
  "processed": "2018-12-03T19:31:11.302Z",
  "device": {
    "channel": "a828de17-b315-4e80-9d2d-35a906afeacf",
    "device_type": "SMS",
    "delivery_address": "15558968663"
  },
  "body": {
    "event_type": "mobile_opt_in",
    "identifiers": {
      "sender": "15558675309",
      "msisdn": "15558968663"
    },
    "properties": {
      "inbound_message": "y",
      "outbound_message": "Do you want to get text alerts from us?",
      "keyword": "Y"
    }
  },
  "type": "COMPLIANCE"
}
  • Occurs when a user opts in to text messages via a keyword.

    OBJECT PROPERTIES
    • body : ObjectRequired

      Contains the event subtype, identifiers, and additional properties about the event.

      OBJECT PROPERTIES
      • event_type : StringRequired

        Indicates that the event represents a newly registered address. Possible values: mobile_opt_in

      • identifiers : ObjectRequired

        Contains the sender and MSISDN for the event.

        OBJECT PROPERTIES
        • msisdn : StringRequired

          The phone number of the user involved in the compliance event.

        • sender : StringRequired

          The phone number or short code of the sender involved in the compliance event.

      • properties : ObjectRequired

        Contains properties specific to the event_type.

        OBJECT PROPERTIES
        • inbound_message : String

          The body of the inbound (to Airship) text message. This is the message a user sent to opt into or out of messages. This text corresponds to the keyword if present.

        • keyword : String

          The keyword the user sent to opt in.

        • outbound_message : String

          The message you sent to the user represented in the event.

    • device : ObjectRequired

      Holds information about an SMS “device” (an individual SMS channel).

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : String

        The phone number for the channel. Format: msisdn

      • device_type : StringRequired

        SMS compliance events list the SMS device type. Possible values: SMS

      • identifiers : Object

        If present, the identifiers object holds the value for the sender property.

        OBJECT PROPERTIES
        • sender : StringRequired

          The sender that the delivery_address received a message from.

SMS Mobile Opt Out Event

Example SMS mobile_opt_out Event

{
  "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d",
  "offset": "1000000701505",
  "occurred": "2018-12-03T19:31:10.000Z",
  "processed": "2018-12-03T19:31:11.302Z",
  "device": {
    "channel": "a828de17-b315-4e80-9d2d-35a906afeacf",
    "device_type": "SMS",
    "delivery_address": "15558968663"
  },
  "body": {
    "event_type": "mobile_opt_out",
    "identifiers": {
      "sender": "15558675309",
      "msisdn": "15558968663"
    },
    "properties": {
      "inbound_message": "STOP",
      "outbound_message": "Text STOP to opt out of text messages from us.",
      "keyword": "STOP"
    }
  },
  "type": "COMPLIANCE"
}
  • Occurs when a user sends a MO message that matches a keyword with an opt-out action. If present, this event would supplant a mobile_keyword_matched event.

    OBJECT PROPERTIES
    • body : ObjectRequired

      Contains the event subtype, identifiers, and additional properties about the event.

      OBJECT PROPERTIES
      • event_type : StringRequired

        The event represents a user who opted out of notifications. Possible values: mobile_opt_out

      • identifiers : ObjectRequired

        Contains the sender and MSISDN for the event.

        OBJECT PROPERTIES
        • msisdn : StringRequired

          The phone number of the user involved in the compliance event.

        • sender : StringRequired

          The phone number or short code of the sender involved in the compliance event.

      • properties : ObjectRequired

        Contains properties specific to the event_type.

        OBJECT PROPERTIES
        • inbound_message : String

          The body of the inbound (to Airship) text message. This is the message a user sent to opt into or out of messages. This text corresponds to the keyword if present.

        • keyword : String

          Indicates that the user responded to opt out of messages. The enumerated values represent default keywords, but any custom keywords that you configure to allow mobile opt-outs can also appear here. Possible values: STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, ARRET

        • outbound_message : String

          The message you sent to the user represented in the event.

    • device : ObjectRequired

      Holds information about an SMS “device” (an individual SMS channel).

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : String

        The phone number for the channel. Format: msisdn

      • device_type : StringRequired

        SMS compliance events list the SMS device type. Possible values: SMS

      • identifiers : Object

        If present, the identifiers object holds the value for the sender property.

        OBJECT PROPERTIES
        • sender : StringRequired

          The sender that the delivery_address received a message from.

SMS Mobile Terminated Message Event

Example mobile_terminated_message Event

{
  "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d",
  "offset": "1000000701505",
  "occurred": "2018-12-03T19:31:10.000Z",
  "processed": "2018-12-03T19:31:11.302Z",
  "device": {
    "channel": "a828de17-b315-4e80-9d2d-35a906afeacf",
    "device_type": "SMS",
    "delivery_address": "15558968663"
  },
  "body": {
    "event_type": "mobile_terminated_message",
    "identifiers": {
      "sender": "15558675309",
      "msisdn": "15558968663"
    }
  },
  "type": "COMPLIANCE"
}
  • Occurs when Airship sends an SMS message to a user. The message represented by this event could be a response to an individual mobile-originated (MO) message, or a message initiated from the Airship UI/API.

    OBJECT PROPERTIES
    • body : ObjectRequired

      Contains the Compliance event subtype and properties specific to the event subtype.

      OBJECT PROPERTIES
      • event_type : StringRequired

        Airship has emitted a mobile-terminated message. Possible values: mobile_terminated_message

      • identifiers : ObjectRequired

        Contains the sender and MSISDN for the event.

        OBJECT PROPERTIES
        • msisdn : StringRequired

          The phone number of the user involved in the compliance event.

        • sender : StringRequired

          The phone number or short code of the sender involved in the compliance event.

    • device : ObjectRequired

      Holds information about an SMS “device” (an individual SMS channel).

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : String

        The phone number for the channel. Format: msisdn

      • device_type : StringRequired

        SMS compliance events list the SMS device type. Possible values: SMS

      • identifiers : Object

        If present, the identifiers object holds the value for the sender property.

        OBJECT PROPERTIES
        • sender : StringRequired

          The sender that the delivery_address received a message from.

SMS Opted Out Event

Example SMS opted_out Event

{
  "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d",
  "offset": "1000000701505",
  "occurred": "2018-12-03T19:31:10.000Z",
  "processed": "2018-12-03T19:31:11.302Z",
  "device": {
    "channel": "a828de17-b315-4e80-9d2d-35a906afeacf",
    "device_type": "SMS",
    "delivery_address": "15558968663"
  },
  "body": {
    "event_type": "opted_out",
    "identifiers": {
      "sender": "15558675309",
      "msisdn": "15558968663"
    }
  },
  "type": "COMPLIANCE"
}
  • Occurs when a user is opted out of an SMS audience via the Airship API, i.e., not via an opt-out keyword. This event type does not contain additional properties.

    All of
    • Object

      OBJECT PROPERTIES
      • device : Object

        Holds information about an SMS “device” (an individual SMS channel).

        OBJECT PROPERTIES
        • channel : String

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

        • delivery_address : String

          The phone number for the channel. Format: msisdn

        • device_type : StringRequired

          SMS compliance events list the SMS device type. Possible values: SMS

        • identifiers : Object

          If present, the identifiers object holds the value for the sender property.

          OBJECT PROPERTIES
          • sender : StringRequired

            The sender that the delivery_address received a message from.

      • id : String

        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

        When the event occurred.

      • offset : String

        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

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

      • type : String

        Compliance events are the only types of events returned by this event stream.

        Possible values: COMPLIANCE

    • Object

      OBJECT PROPERTIES
      • body : ObjectRequired

        Contains the event subtype, identifiers, and additional properties about the event.

        OBJECT PROPERTIES
        • event_type : StringRequired

          The address opted out of notifications. Possible values: opted_out

        • identifiers : ObjectRequired

          Contains the sender and MSISDN for the event.

          OBJECT PROPERTIES
          • msisdn : StringRequired

            The phone number of the user involved in the compliance event.

          • sender : StringRequired

            The phone number or short code of the sender involved in the compliance event.

SMS Create-and-Send Event

Example SMS create_and_send Event

{
  "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d",
  "offset": "1000000701505",
  "occurred": "2018-12-03T19:31:10.000Z",
  "processed": "2018-12-03T19:31:11.302Z",
  "device": {
    "channel": "a828de17-b315-4e80-9d2d-35a906afeacf",
    "device_type": "SMS",
    "delivery_address": "15558968663"
  },
  "body": {
    "event_type": "create_and_send",
    "identifiers": {
      "sender": "15558675309",
      "msisdn": "15558968663"
    },
    "properties": {
      "opted_in": "2018-12-03T19:31:10.000Z",
      "channel_registered": "true"
    }
  },
  "type": "COMPLIANCE"
}
  • An event that occurs for SMS channels used as a part of a create-and-send message.

    OBJECT PROPERTIES
    • body : ObjectRequired

      Contains the event subtype and additional properties about the event.

      OBJECT PROPERTIES
      • event_type : StringRequired

        Possible values: create_and_send

      • identifiers : ObjectRequired

        Contains the sender and MSISDN for the event.

        OBJECT PROPERTIES
        • msisdn : StringRequired

          The phone number of the user involved in the compliance event.

        • sender : StringRequired

          The phone number or short code of the sender involved in the compliance event.

      • properties : ObjectRequired

        Properties for an SMS create-and-send event.

        OBJECT PROPERTIES
        • channel_registered : BooleanRequired

          If true, a new channel was created to represent the identifiers in the event. If false, the address was already registered to Airship.

        • opted_in : String

          The date-and-time when the msisdn opted into messages from the sender.

    • device : ObjectRequired

      Holds information about an SMS “device” (an individual SMS channel).

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : String

        The phone number for the channel. Format: msisdn

      • device_type : StringRequired

        SMS compliance events list the SMS device type. Possible values: SMS

      • identifiers : Object

        If present, the identifiers object holds the value for the sender property.

        OBJECT PROPERTIES
        • sender : StringRequired

          The sender that the delivery_address received a message from.

SMS Registration Event

Example SMS Registration Event

{
  "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d",
  "offset": "1000000701505",
  "occurred": "2018-12-03T19:31:10.000Z",
  "processed": "2018-12-03T19:31:11.302Z",
  "device": {
    "channel": "a828de17-b315-4e80-9d2d-35a906afeacf",
    "device_type": "SMS",
    "delivery_address": "15558968663"
  },
  "body": {
    "event_type": "registration",
    "identifiers": {
      "sender": "15558675309",
      "msisdn": "15558968663"
    },
    "properties": {
      "opted_in": "2018-12-03T19:31:10.000Z",
      "registration_type": "created"
    }
  },
  "type": "COMPLIANCE"
}
  • Occurs when a user opts in to receive SMS messages from you, via a call to the SMS registration API.

    OBJECT PROPERTIES
    • body : ObjectRequired

      Contains the event subtype, identifiers, and additional properties about the event.

      OBJECT PROPERTIES
      • event_type : StringRequired

        Indicates that the event represents a newly registered address. Possible values: registration

      • identifiers : ObjectRequired

        Contains the sender and MSISDN for the event.

        OBJECT PROPERTIES
        • msisdn : StringRequired

          The phone number of the user involved in the compliance event.

        • sender : StringRequired

          The phone number or short code of the sender involved in the compliance event.

      • properties : ObjectRequired

        Contains properties specific to the event_type.

        OBJECT PROPERTIES
        • opted_in : StringRequired

          The ISO 8601 datetime (UTC) when the channel opted-in to notifications.

        • registration_type : StringRequired

          Indicates whether the channel was created or updated. Possible values: create, update

    • device : ObjectRequired

      Holds information about an SMS “device” (an individual SMS channel).

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : String

        The phone number for the channel. Format: msisdn

      • device_type : StringRequired

        SMS compliance events list the SMS device type. Possible values: SMS

      • identifiers : Object

        If present, the identifiers object holds the value for the sender property.

        OBJECT PROPERTIES
        • sender : StringRequired

          The sender that the delivery_address received a message from.

SMS Uninstalled Event

Example SMS uninstalled Event

{
  "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d",
  "offset": "1000000701505",
  "occurred": "2018-12-03T19:31:10.000Z",
  "processed": "2018-12-03T19:31:11.302Z",
  "device": {
    "channel": "a828de17-b315-4e80-9d2d-35a906afeacf",
    "device_type": "SMS",
    "delivery_address": "15558968663"
  },
  "body": {
    "event_type": "uninstall",
    "identifiers": {
      "sender": "15558675309",
      "msisdn": "15558968663"
    }
  },
  "type": "COMPLIANCE"
}
  • Occurs when the SMS uninstall API is called.

    OBJECT PROPERTIES
    • body : ObjectRequired

      Contains the event subtype, identifiers, and additional properties about the event.

      OBJECT PROPERTIES
      • event_type : StringRequired

        The address was uninstalled. Possible values: uninstall

      • identifiers : ObjectRequired

        Contains the sender and MSISDN for the event.

        OBJECT PROPERTIES
        • msisdn : StringRequired

          The phone number of the user involved in the compliance event.

        • sender : StringRequired

          The phone number or short code of the sender involved in the compliance event.

    • device : ObjectRequired

      Holds information about an SMS “device” (an individual SMS channel).

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : String

        The phone number for the channel. Format: msisdn

      • device_type : StringRequired

        SMS compliance events list the SMS device type. Possible values: SMS

      • identifiers : Object

        If present, the identifiers object holds the value for the sender property.

        OBJECT PROPERTIES
        • sender : StringRequired

          The sender that the delivery_address received a message from.

Custom Email Events

Airship delivers email messages through a provider (SparkPost). Custom email events represent events that occur at the provider level — outside Airship, between the provider and recipient.

Email Bounce Event

Example email bounce custom event

{
  "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e",
  "offset": "1000001778145",
  "occurred": "2019-02-27T23:20:14.000Z",
  "processed": "2019-02-27T23:20:49.347Z",
  "device": {
      "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
      "device_type": "EMAIL",
      "delivery_address": "new.subscriber@email.com"
  },
  "body": {
      "name": "bounce",
      "triggering_push": {
          "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99",
          "campaigns": {
              "categories": [
                  "new",
                  "Baseball Fan"
              ]
          }
      },
      "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9",
      "source": "API",
      "properties": {
        "sender": "baseball@sports.com",
        "subject": "Baseball Season is Almost Here!",
        "email": "new.subscriber@email.com",
        "bounce_event_type": "bounce",
        "bounce_class": "10",
      }
  },
  "type": "CUSTOM"
}
  • Occurs when an email could not be delivered to an address. The bounce_class provides additional information about the reason your message bounced. This event occurs in conjunction with a similar COMPLIANCE event.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • name : StringRequired

        Possible values: bounce

      • properties : ObjectRequired

        All of
        • Object

          OBJECT PROPERTIES
          • email : String

            The recipient’s email address.

          • sender : String

            The sender of the email specified by the event.

          • subject : String

            The subject line of the email specified by the event.

        • Object

          OBJECT PROPERTIES
          • bounce_class : String

            A number between 1 and 100 that represents the specific reason the email abounced. Format: (100)|[1-9]\d?

          • bounce_event_type : String

            Possible values: bounce

      • session_id : String

        Represents the “session” of user activity. Absent if the application was initialized while backgrounded. Format: uuid

      • source : StringRequired

        Possible values: API

      • triggering_push : ObjectRequired

        The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.

        An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.

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

          A unique identifier for a push operation. Format: uuid

        • time : String

          The UTC time when the push occurred.

        • 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 : ObjectRequired

      Holds information about the email “device” (an individual email channel) the event occurred against.

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : StringRequired

        The email address of the channel the event occured against.

      • device_type : StringRequired

        email compliance events use the EMAIL device type. Possible values: EMAIL

      • named_user : String

        The named user that the channel is associated with; appears only if the channel is associated with a named user.

Email Click Event

Example email click custom event

{
  "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e",
  "offset": "1000001778145",
  "occurred": "2019-02-27T23:20:14.000Z",
  "processed": "2019-02-27T23:20:49.347Z",
  "device": {
      "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
      "device_type": "EMAIL",
      "delivery_address": "new.subscriber@email.com"
  },
  "body": {
      "name": "click",
      "triggering_push": {
          "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99",
          "campaigns": {
              "categories": [
                  "new",
                  "Baseball Fan"
              ]
          }
      },
      "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9",
      "source": "API",
      "properties": {
          "sender": "baseball@sports.com",
          "subject": "Baseball Season is Almost Here!",
          "email": "new.subscriber@email.com",
          "link_name": "Click here for baseball updates",
          "link_url": "http://www.urbanairship.com",
      }
  },
  "type": "CUSTOM"
}
  • Occurs when a recipient clicks a tracked link in a message. Tracked links are redirected through the provider’s click-tracking server to record the event.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • name : StringRequired

        Possible values: click

      • properties : ObjectRequired

        All of
        • Object

          OBJECT PROPERTIES
          • email : String

            The recipient’s email address.

          • sender : String

            The sender of the email specified by the event.

          • subject : String

            The subject line of the email specified by the event.

        • Object

          OBJECT PROPERTIES
          • The link text that the user clicked.

          • The URL of the link that the user clicked.

      • session_id : String

        Represents the “session” of user activity. Absent if the application was initialized while backgrounded. Format: uuid

      • source : StringRequired

        Possible values: API

      • triggering_push : ObjectRequired

        The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.

        An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.

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

          A unique identifier for a push operation. Format: uuid

        • time : String

          The UTC time when the push occurred.

        • 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 : ObjectRequired

      Holds information about the email “device” (an individual email channel) the event occurred against.

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : StringRequired

        The email address of the channel the event occured against.

      • device_type : StringRequired

        email compliance events use the EMAIL device type. Possible values: EMAIL

      • named_user : String

        The named user that the channel is associated with; appears only if the channel is associated with a named user.

Email Delay Event

Example email delivery custom event

{
  "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e",
  "offset": "1000001778145",
  "occurred": "2019-02-27T23:20:14.000Z",
  "processed": "2019-02-27T23:20:49.347Z",
  "device": {
      "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
      "device_type": "EMAIL",
      "delivery_address": "addressResponding4xx@email.com"
  },
  "body": {
      "name": "delay",
      "triggering_push": {
          "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99",
          "campaigns": {
              "categories": [
                  "new",
                  "Baseball Fan"
              ]
          }
      },
      "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9",
      "source": "API",
      "properties": {
          "sender": "baseball@sports.com",
          "subject": "Baseball Season is Almost Here!",
          "email": "addressResponding4xx@email.com"
      }
  },
  "type": "CUSTOM"
}
  • Occurs when a mailbox provider temporarily rejects an email. In general, this event indicates that the provider will attempt to resend the message.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • name : StringRequired

        Possible values: delay

      • properties : ObjectRequired

        OBJECT PROPERTIES
        • email : String

          The recipient’s email address.

        • sender : String

          The sender of the email specified by the event.

        • subject : String

          The subject line of the email specified by the event.

      • session_id : String

        Represents the “session” of user activity. Absent if the application was initialized while backgrounded. Format: uuid

      • source : StringRequired

        Possible values: API

      • triggering_push : ObjectRequired

        The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.

        An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.

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

          A unique identifier for a push operation. Format: uuid

        • time : String

          The UTC time when the push occurred.

        • 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 : ObjectRequired

      Holds information about the email “device” (an individual email channel) the event occurred against.

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : StringRequired

        The email address of the channel the event occured against.

      • device_type : StringRequired

        email compliance events use the EMAIL device type. Possible values: EMAIL

      • named_user : String

        The named user that the channel is associated with; appears only if the channel is associated with a named user.

Email Delivery Event

Example email delivery custom event

{
  "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e",
  "offset": "1000001778145",
  "occurred": "2019-02-27T23:20:14.000Z",
  "processed": "2019-02-27T23:20:49.347Z",
  "device": {
      "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
      "device_type": "EMAIL",
      "delivery_address": "new.subscriber@email.com"
  },
  "body": {
      "name": "delivery",
      "triggering_push": {
          "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99",
          "campaigns": {
              "categories": [
                  "new",
                  "Baseball Fan"
              ]
          }
      },
      "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9",
      "source": "API",
      "properties": {
          "sender": "baseball@sports.com",
          "subject": "Baseball Season is Almost Here!",
          "email": "new.subscriber@email.com"
      }
  },
  "type": "CUSTOM"
}
  • Occurs when the remote MTA (email server) acknowledges receipt of a message.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • name : StringRequired

        Possible values: delivery

      • properties : ObjectRequired

        OBJECT PROPERTIES
        • email : String

          The recipient’s email address.

        • sender : String

          The sender of the email specified by the event.

        • subject : String

          The subject line of the email specified by the event.

      • session_id : String

        Represents the “session” of user activity. Absent if the application was initialized while backgrounded. Format: uuid

      • source : StringRequired

        Possible values: API

      • triggering_push : ObjectRequired

        The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.

        An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.

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

          A unique identifier for a push operation. Format: uuid

        • time : String

          The UTC time when the push occurred.

        • 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 : ObjectRequired

      Holds information about the email “device” (an individual email channel) the event occurred against.

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : StringRequired

        The email address of the channel the event occured against.

      • device_type : StringRequired

        email compliance events use the EMAIL device type. Possible values: EMAIL

      • named_user : String

        The named user that the channel is associated with; appears only if the channel is associated with a named user.

Email Initial Open Event

Example email initial_open custom event

{
  "id": "544da998-9338-4506-8564-8adf7b2597cf",
  "offset": "1000032367699",
  "occurred": "2020-07-29T20:26:03.000Z",
  "processed": "2020-07-29T20:27:47.780Z",
  "device": {
    "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
    "device_type": "EMAIL",
    "delivery_address": "new.subscriber@email.com",
    "named_user_id": "a_person"
  },
  "body": {
    "name": "initial_open",
    "triggering_push": {
      "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99"
    },
    "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9",
    "source": "API",
    "properties": {
      "sender": "baseball@sports.com",
      "subject": "Baseball Season is Almost Here!",
      "email": "new.subscriber@email.com"
    }
  },
  "type": "CUSTOM"
}
  • Occurs when a recipient first opens an email, rendering a tracking pixel at the top of the email.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • name : StringRequired

        Possible values: initial_open

      • properties : ObjectRequired

        OBJECT PROPERTIES
        • email : String

          The recipient’s email address.

        • sender : String

          The sender of the email specified by the event.

        • subject : String

          The subject line of the email specified by the event.

      • session_id : String

        Represents the “session” of user activity. Absent if the application was initialized while backgrounded. Format: uuid

      • source : StringRequired

        Possible values: API

      • triggering_push : ObjectRequired

        The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.

        An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.

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

          A unique identifier for a push operation. Format: uuid

        • time : String

          The UTC time when the push occurred.

        • 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 : ObjectRequired

      Holds information about the email “device” (an individual email channel) the event occurred against.

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : StringRequired

        The email address of the channel the event occured against.

      • device_type : StringRequired

        email compliance events use the EMAIL device type. Possible values: EMAIL

      • named_user : String

        The named user that the channel is associated with; appears only if the channel is associated with a named user.

Email Injection Event

Example email injection custom event

{
  "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e",
  "offset": "1000001778145",
  "occurred": "2019-02-27T23:20:14.000Z",
  "processed": "2019-02-27T23:20:49.347Z",
  "device": {
      "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
      "device_type": "EMAIL",
      "delivery_address": "new.subscriber@email.com"
  },
  "body": {
      "name": "injection",
      "triggering_push": {
          "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99",
          "campaigns": {
              "categories": [
                  "new",
                  "Baseball Fan"
              ]
          }
      },
      "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9",
      "source": "API",
      "properties": {
          "sender": "baseball@sports.com",
          "subject": "Baseball Season is Almost Here!",
          "email": "new.subscriber@email.com"
      }
  },
  "type": "CUSTOM"
}
  • This event occurs when the provider (SparkPost) receives a message — typically when a member of the audience responds to an email.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • name : StringRequired

        Possible values: injection

      • properties : ObjectRequired

        OBJECT PROPERTIES
        • email : String

          The recipient’s email address.

        • sender : String

          The sender of the email specified by the event.

        • subject : String

          The subject line of the email specified by the event.

      • session_id : String

        Represents the “session” of user activity. Absent if the application was initialized while backgrounded. Format: uuid

      • source : StringRequired

        Possible values: API

      • triggering_push : ObjectRequired

        The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.

        An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.

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

          A unique identifier for a push operation. Format: uuid

        • time : String

          The UTC time when the push occurred.

        • 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 : ObjectRequired

      Holds information about the email “device” (an individual email channel) the event occurred against.

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : StringRequired

        The email address of the channel the event occured against.

      • device_type : StringRequired

        email compliance events use the EMAIL device type. Possible values: EMAIL

      • named_user : String

        The named user that the channel is associated with; appears only if the channel is associated with a named user.

Email Open Event

Example email open custom event

{
  "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e",
  "offset": "1000001778145",
  "occurred": "2019-02-27T23:20:14.000Z",
  "processed": "2019-02-27T23:20:49.347Z",
  "device": {
      "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
      "device_type": "EMAIL",
      "delivery_address": "new.subscriber@email.com"
  },
  "body": {
      "name": "open",
      "triggering_push": {
          "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99",
          "campaigns": {
              "categories": [
                  "new",
                  "Baseball Fan"
              ]
          }
      },
      "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9",
      "source": "API",
      "properties": {
          "sender": "baseball@sports.com",
          "subject": "Baseball Season is Almost Here!",
          "email": "new.subscriber@email.com"
      }
  },
  "type": "CUSTOM"
}
  • Occurs when a recipient opens an email, rendering a tracking pixel at the bottom of the message. If a message is truncated by a client or email provider, a user may have to open it in a separate window to render the tracking pixel (and register this event).

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • name : StringRequired

        Possible values: open

      • properties : ObjectRequired

        OBJECT PROPERTIES
        • email : String

          The recipient’s email address.

        • sender : String

          The sender of the email specified by the event.

        • subject : String

          The subject line of the email specified by the event.

      • session_id : String

        Represents the “session” of user activity. Absent if the application was initialized while backgrounded. Format: uuid

      • source : StringRequired

        Possible values: API

      • triggering_push : ObjectRequired

        The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.

        An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.

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

          A unique identifier for a push operation. Format: uuid

        • time : String

          The UTC time when the push occurred.

        • 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 : ObjectRequired

      Holds information about the email “device” (an individual email channel) the event occurred against.

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : StringRequired

        The email address of the channel the event occured against.

      • device_type : StringRequired

        email compliance events use the EMAIL device type. Possible values: EMAIL

      • named_user : String

        The named user that the channel is associated with; appears only if the channel is associated with a named user.

Email Unsubscribe Link Event

Example email unsubscribe link custom event

{
  "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e",
  "offset": "1000001778145",
  "occurred": "2019-02-27T23:20:14.000Z",
  "processed": "2019-02-27T23:20:49.347Z",
  "device": {
      "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
      "device_type": "EMAIL",
      "delivery_address": "new.subscriber@email.com"
  },
  "body": {
      "name": "unsubscribe",
      "triggering_push": {
          "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99",
          "campaigns": {
              "categories": [
                  "new",
                  "Baseball Fan"
              ]
          }
      },
      "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9",
      "source": "API",
      "properties": {
        "unsubscribe_event_type": "link_unsubscribe"
      }
  },
  "type": "CUSTOM"
}
  • Occurs when a user clicks an unsubscribe link in an email you sent.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • name : StringRequired

        Possible values: unsubscribe

      • properties : ObjectRequired

        OBJECT PROPERTIES
        • unsubscribe_event_type : String

          Possible values: link_unsubscribe

      • session_id : String

        Represents the “session” of user activity. Absent if the application was initialized while backgrounded. Format: uuid

      • source : StringRequired

        Possible values: API

      • triggering_push : ObjectRequired

        The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.

        An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.

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

          A unique identifier for a push operation. Format: uuid

        • time : String

          The UTC time when the push occurred.

        • 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 : ObjectRequired

      Holds information about the email “device” (an individual email channel) the event occurred against.

      OBJECT PROPERTIES
      • channel : String

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

      • delivery_address : StringRequired

        The email address of the channel the event occured against.

      • device_type : StringRequired

        email compliance events use the EMAIL device type. Possible values: EMAIL

      • named_user : String

        The named user that the channel is associated with; appears only if the channel is associated with a named user.

Device Information

-| Events are ascribed to devices. App, web, sms, email, and open channel “devices” return different information.

App Device Information

  • Information about app users generated by the SDK.

    OBJECT PROPERTIES
    • amazon_channel : String

      The identifier for an Amazon channel. In general, this is also the same value as the “channel”

    • android_channel : String

      The identifier for an Android channel. In general, this is also the same value as the “channel”

    • attributes : Object

      Attributes specific to app devices.

      OBJECT PROPERTIES
      • app_package_name : String

        A unique identifier for the app name.

      • app_version : String

        The version of the app.

      • background_push_enabled : String

        Indicates whether or not the device has background push notifications enabled. Possible values: true, false

      • carrier : String

        The wireless carrier used by the device.

      • connection_type : String

        The internet connection type used by the device. Possible values: WIFI, CELL, WIMAX, NONE

      • device_model : String

        The device model.

      • device_os : String

        The device operating system.

      • iana_timezone : String

        The time zone of the device.

      • locale_country_code : String

        The ISO-3166-1 country code as defined in device settings.

      • locale_language_code : String

        The ISO-639-1 two-letter language code reflecting the language that the device is set to.

      • locale_timezone : String

        The device’s timezone offset in seconds from UTC.

      • locale_variant : String

        The language variant

      • location_enabled : String

        Indicates whether or not the device has location services enabled. Possible values: true, false

      • location_permission : String

        • SYSTEM_LOCATION_DISABLED Location is disabled in system settings
        • NOT_ALLOWED Android: missing manifest permissions, iOS: opted out
        • ALWAYS_ALLOWED Android: has manifest permissions, iOS: opted in background and foreground
        • FOREGROUND_ALLOWED iOS only: opted in foreground only
        • UNPROMPTED: iOS only

        Possible values: SYSTEM_LOCATION_DISABLED, NOT_ALLOWED, ALWAYS_ALLOWED, FOREGROUND_ALLOWED, UNPROMPTED

      • push_opt_in : String

        Indicates whether or not the device is opted into push notifications.

      • ua_sdk_version : String

        The version of the Airship SDK used in the app.

    • channel : StringRequired

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

    • device_type : StringRequired

      The platform that the channel is on. Possible values: IOS, ANDROID, AMAZON

    • identifiers : Object

      Identifying information specific to app devices.

      OBJECT PROPERTIES
      • com.urbanairship.aaid : String

        Android/Amazon ad identifier Format: uuid

      • com.urbanairship.gimbal.aii : String

        Gimbal application instance identifier Format: uuid

      • com.urbanairship.idfa : String

        Apple ad identifier Format: uuid

      • com.urbanairship.limited_ad_tracking_enabled : String

        If true, the user has enabled limited ad tracking. Possible values: true, false

      • com.urbanairship.vendor : String

        Apple vendor identifier Format: uuid

    • ios_channel : String

      The identifier for an iOS channel. In general, this is also the same value as the “channel”

    • named_user_id : String

      the named user identifier for the device.

Open Channel Device Information

  • Information about open channel users.

    OBJECT PROPERTIES
    • channel : String

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

    • device_type : String

      The platform that the channel is on. Possible values: OPEN

    • named_user_id : String

      the named user identifier for the device.

    • open_platform_name : String

      If device_type is set to OPEN, this field shows the full name of the platform.

Device Information for SMS and Email

  • Information about the SMS or Email device related to an event.

    OBJECT PROPERTIES
    • channel : StringRequired

      the channel identifier

    • delivery_address : String

      • If ‘device_type’ is ‘SMS’, this field shows the MSISDN.
      • If device_type is EMAIL, this field shows the email address.

    • device_type : StringRequired

      The platform that the channel is on. Possible values: EMAIL, SMS

    • named_user_id : String

      The named user the channel is associated with.

Web Device Information

  • Information about web users generated by the SDK.

    OBJECT PROPERTIES
    • attributes : Object

      OBJECT PROPERTIES
      • iana_timezone : String

        The time zone of the device.

      • locale_country_code : String

        The ISO-3166-1 country code as defined in device settings.

      • locale_language_code : String

        The ISO-639-1 two-letter language code reflecting the language that the device is set to.

      • locale_timezone : String

        The device’s timezone offset in seconds from UTC.

      • locale_variant : String

        The language variant

      • push_opt_in : StringRequired

        Indicates whether or not the device is opted into push notifications.

      • ua_sdk_version : StringRequired

        The version of the Airship SDK used in the app.

      • web_browser_name : StringRequired

        The name of the browser running the SDK.

      • web_browser_type : StringRequired

        Indicates whether the browser was running on a desktop or mobile device.

      • web_browser_version : StringRequired

        The version of the browser.

      • web_user_agent_string : StringRequired

        The user agent reported by the browser.

    • channel : StringRequired

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

    • device_type : StringRequired

      The platform that the channel is on. Possible values: WEB

    • named_user_id : String

      the named user identifier for the device.

Custom SMS Events

Airship delivers SMS messages through a provider (Sinch, formerly known as CLX). Custom SMS events represent events that occur at the provider level — outside Airship, between the provider and recipient.

SMS Delivery Report

Example Delivery Report Event

{
  "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"
}
  • 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.

    OBJECT PROPERTIES
    • body : ObjectRequired

      OBJECT PROPERTIES
      • interaction_type : String

        Possible values: delivery_report

      • name : StringRequired

        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.

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

      • properties : AnyRequired

        One of
        • SMS Delivery Properties : Object

          A delivery report for SMS.

          OBJECT PROPERTIES
          • error_code : String

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

          • sender : StringRequired

            The number or short code that the message originated from.

          • vendor : StringRequired

            The delivery service for the message. Possible values: CLX, TYNTEC

          • vendorDeliveryId : StringRequired

            A unique identifier for the message from the SMS vendor.

        • MMS Delivery Properties : Object

          A delivery report for MMS.

          OBJECT PROPERTIES
          • 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.

          • result_code : StringRequired

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

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

            The delivery service for the message. Possible values: CLX

      • source : StringRequired

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

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

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

      OBJECT PROPERTIES
      • channel : StringRequired

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

      • delivery_address : StringRequired

        The phone number associated with the channel.

      • device_type : StringRequired

        Possible values: SMS

    • id : StringRequired

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

      When the event occurred.

    • offset : StringRequired

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

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

    • type : StringRequired

      Possible values: CUSTOM

Request Filters

Device Filter

{
   "devices": [
       {
           "channel": "195adec2-fa70-4e62-b978-78ede2827597"
       },
       {
           "named_user_id": "George"
       }
   ]
}

Example Notification Filter - Include All Events Pertaining to a Push ID

{"push_id": "0c173744-dd35-4b5e-9f7f-2b7e0ce0e36e"}

Example Notification Filter - Include all events pertaining to a pipeline or PLT Push (Defined by Group ID)

{"group_id": "b7f7c9e0-64d6-4f44-9d74-d32ef5437ccf"}
  • An array of filter objects defining the events you want to see in the event stream. A filter object defines a function that either passes or fails an event. Events are included in the response if they pass any of the functions defined by the objects in the array.

    ARRAY ITEM
    • OBJECT PROPERTIES
      • device_types : Array [String]

        Returns events pertaining to devices on the specified platform(s).

      • devices : Array [Any]

        Limits the stream to events relating to specific device attributes.

        ARRAY ITEM
        • Any of
          • Object

            OBJECT PROPERTIES
            • channel : String

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

          • Object

            OBJECT PROPERTIES
            • named_user_id : String

              The named user for a device. The event stream will return events pertaining to the named user.

      • latency : Integer

        The number of milliseconds between the current time and when the event(s) you want to return occured. If an event occurred more than latency milliseconds ago, it is filtered out of the event stream. Format: milliseconds

      • notifications : Any

        Limits the stream to events related to one or more specific pushes. This allows you to easily track the events generated by a given push or pipeline. In this object, you should only specify one of push_id or group_id. Child pushes may be included in the returned stream. If they are, they will have a Group ID relating them back to the PLT or automation specification that spawned them.

        One of
        • Push ID : Object

          OBJECT PROPERTIES
          • push_id : String

            The push you want to return events for.

        • Group ID : Object

          OBJECT PROPERTIES
          • group_id : String

            The group you want to return events for.

      • types : Array [String]

        Specifies the event types you want to return in the event stream.

Request Subset

Subset SAMPLE

{
  "type": "SAMPLE",
  "proportion": 0.1
}

Subset PARTITION

{
  "type": "PARTITION",
  "count": 10,
  "selection": 0
}
  • Use subsets to return a proportion of the event stream and not all events meeting your other criteria. The subset object defines the proportion of the event stream that you want to return.

    OBJECT PROPERTIES
    • count : Integer

      Required when the type is PARTITION. The value is the number of partitions you want to devide the event stream into.

    • proportion : Number

      Required when the type is SAMPLE. Specifies the percentage of events that will appear in the response, chosen randomly. Format: float Max: 1

    • selection : Integer

      Required when the type is PARTITION. The value is the partition that you want to return in the response. Must be less than count.

    • type : String

      The type of partition, SAMPLE or PARTITION.

      • SAMPLE returns a random sample of events; the sample proportion determines the fraction of total events that Real-time Data Streaming returns.
      • PARTITION segments the event stream into a number of partitions (determined by count) and returns a single partition in the event stream (determined by selection). Possible values: SAMPLE, PARTITION