Event Stream data reference

Access event stream data using Liquid syntax. Wrap any field in {{ }} to include it in your Event Stream body. See Examples.

Message data for Journeys and API sends is retained for 30 days. Interaction events (clicks, opens, unsubscribes) that occur after 30 days may have blank message properties. To recover the data, correlate the message.id from the interaction event with the original sent event, which contains the full message data.

`event` properties

Every event includes the core fields below. Channel-specific fields under event.data.* are included only when applicable. See Channel-specific fields.

string

The event type, combining channel and action (e.g. message.push.clicked, message.email.bounced). See the full list of values in the event kind reference below. Liquid: {{ event.kind }}

string

A unique, OneSignal-generated identifier for each individual event in UUID v4 format. Use this ID for idempotent delivery tracking. For the message or template identifier, use message.id or message.template_id. Liquid: {{ event.id }}

integer

UNIX timestamp of the event. Liquid: {{ event.timestamp }}

string

Human-readable time of the event in UTC as an ISO 8601 string (e.g., “2024-02-21T23:45:15.228Z”). Liquid: {{ event.datetime }}

string

The OneSignal App ID. Liquid: {{ event.app_id }}

string

The subscription’s platform or channel. Returned values depend on the channel:

Mobile push: iOS, Android, Huawei, FireOS
Web push: Chrome, Firefox, Safari
Email: Email
SMS: SMS

Liquid: {{ event.subscription_device_type }}

string

The OneSignal Subscription ID for the Subscription that received this message. This is the same value as user.subscription.id; both fields are provided so you can address the Subscription from either the event or user namespace. Liquid: {{ event.subscription_id }}

string

The OneSignal User ID (UUID v4 format). Liquid: {{ event.onesignal_id }}

string

Your user ID set as the OneSignal External ID alias. Empty if no External ID has been set on the user. Liquid: {{ event.external_id }}

Channel-specific fields

Some event kinds carry extra context that doesn’t apply to other channels. For example, the target_id of a button tapped in an in-app message, or the failure_reason for a bounced email. These fields are namespaced under event.data.* so the top-level event.* schema stays consistent across all event kinds. A field is populated only when the event kind includes it; otherwise it renders as an empty string.

In-app message events

Included with message.iam.* events. See In-app message Event Streams for details.

string

The name of the in-app message page or card displayed. Liquid: {{ event.data.page_name }}

string

Unique identifier for the in-app message page or card displayed. Liquid: {{ event.data.page_id }}

string

The name of the button or image block element clicked. The element must contain an in-app click action. Liquid: {{ event.data.target_name }}

string

Unique identifier for the button or image block element clicked. Liquid: {{ event.data.target_id }}

Live Activity events

Included with message.live_activity.* events.

string

Unique identifier for a specific Live Activity (e.g., “Knicks vs Cavs - Oct 22 7PM”). Liquid: {{ event.data.live_activity_id }}

string

Grouping label for Live Activity categories (e.g., “Knicks_games”). Liquid: {{ event.data.live_activity_type }}

Failed events

Included with message.push.failed and message.email.failed events.

string

The reason the message failed to send. See Push Message Reports or Email Message Reports for common reasons. Liquid: {{ event.data.failure_reason }}

Event kind reference

For detailed definitions of each metric, see the Metrics Glossary.

message.push.received is only emitted when Confirmed receipt is enabled. Without it, OneSignal cannot determine whether a push notification reached the device. If your Event Stream depends on this event, verify confirmed receipt is enabled for your app first. Otherwise these events will never fire.

Message Event Kind (OneSignal)	Event name (in data set)	Event Description
Push Delivered	`message.push.sent`	Push notification successfully delivered to the push services (FCM, APNs).
Push Received	`message.push.received`	Push notification received by recipient. Not available on all platforms. See Confirmed receipt for more details.
Push Clicked	`message.push.clicked`	User tapped the push notification to open the app on device.
Push Failed	`message.push.failed`	Push failed to be sent. See Push Message Reports for details.
Push Unsubscribed	`message.push.unsubscribed`	The push Subscriptions that did not receive the notification because they uninstalled the app, cleared browser data, or opted out and have not opened the app since. OneSignal will not retry to this Subscription in future messages unless the user re-subscribes and opens the app. This is a reachability state detected at send time, when the push service (FCM, APNs) reports the token as invalid, not an opt-out triggered by this message. Unlike email Unsubscribed (an opt-out action on a specific message), push Unsubscribed reflects an earlier unsubscribe and cannot be attributed to this message’s timing or content. For more details see When do push Subscription statuses update?.
In-App Impression	`message.iam.impression`	In-App Message successfully displayed on device.
In-App Clicked	`message.iam.clicked`	User tapped an element on the In-App Message.
In-App Page Displayed	`message.iam.page_displayed`	In-App Message page was displayed. Helpful for tracking carousels.
Email Sent	`message.email.sent`	Email successfully sent.
Email Received	`message.email.received`	Email received by recipient.
Email Opened	`message.email.opened`	Email was opened by recipient. See Email Message Reports for details.
Email Link Clicked	`message.email.clicked`	User tapped a link in the email.
Email Unsubscribed	`message.email.unsubscribed`	User unsubscribed from email via the unsubscribe link.
Email Reported As Spam	`message.email.reported_as_spam`	User reported the email as spam. Gmail requires Google Postmaster Tools to track. See Email deliverability for more details.
Email Bounced	`message.email.bounced`	Email returned to sender due to permanent error. See Email Message Reports for details.
Email Failed	`message.email.failed`	Email could not be delivered. See Email Message Reports for details.
Email Suppressed	`message.email.suppressed`	Email could not be sent because the email address is on the Suppression list.
SMS Sent	`message.sms.sent`	SMS sent to recipient.
SMS Failed	`message.sms.failed`	SMS failed to send. See SMS Message Reports for details.
SMS Delivered	`message.sms.delivered`	SMS successfully delivered.
SMS Undelivered	`message.sms.undelivered`	SMS could not be sent. See SMS Message Reports for details.
Live Activity Sent	`message.live_activity.sent`	Live Activity successfully sent to APNs.
Live Activity Delivered	`message.live_activity.delivered`	Live Activity received by recipient.
Live Activity Unsubscribed	`message.live_activity.unsubscribed`	User unsubscribed from Live Activities.
Live Activity Failed	`message.live_activity.failed`	Live Activity failed to send.
Live Activity Clicked	`message.live_activity.clicked`	Live Activity clicked by user.

Example event object

Copy this Liquid template into your Event Stream body to capture all event fields:

JSON

{
  "event.kind": "{{ event.kind }}",
  "event.id": "{{ event.id }}",
  "event.timestamp": "{{ event.timestamp }}",
  "event.datetime": "{{ event.datetime }}",
  "event.app_id": "{{ event.app_id }}",
  "event.subscription_device_type": "{{ event.subscription_device_type }}",
  "event.subscription_id": "{{ event.subscription_id }}",
  "event.onesignal_id": "{{ event.onesignal_id }}",
  "event.external_id": "{{ event.external_id }}",
  "event.data.page_name": "{{ event.data.page_name }}",
  "event.data.page_id": "{{ event.data.page_id }}",
  "event.data.target_name": "{{ event.data.target_name }}",
  "event.data.target_id": "{{ event.data.target_id }}",
  "event.data.failure_reason": "{{ event.data.failure_reason }}"
}

Example rendered output

What a push click event looks like after Liquid rendering:

JSON

{
  "event.kind": "message.push.clicked",
  "event.id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event.timestamp": 1708559115,
  "event.datetime": "2024-02-21T23:45:15.228Z",
  "event.app_id": "your-onesignal-app-id",
  "event.subscription_device_type": "iOS",
  "event.subscription_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "event.onesignal_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "event.external_id": "user_12345",
  "event.data.page_name": "",
  "event.data.page_id": "",
  "event.data.target_name": "",
  "event.data.target_id": "",
  "event.data.failure_reason": ""
}

Channel-specific fields like event.data.page_name are empty for event kinds that don’t include them.

`message` properties

The message object describes the message sent to the end-user, including its ID, template, content, and URLs.

string

The message ID generated by OneSignal. Liquid: {{ message.id }}

string

The name of the message as set in the dashboard or using the API name property. Liquid: {{ message.name }}

object

The push message title or email subject. For push, returns a localized object like {'en':'Your title'}. For email, returns the subject line as a plain string. Set via the dashboard or the API headings / email_subject properties. Liquid: {{ message.title }}

For push events, {{ message.title }} and {{ message.contents }} render as Python-style dicts ({'en':'…'}) rather than valid JSON, which breaks downstream parsers. To extract the locale string, use dot notation: {{ message.title.en }} or {{ message.contents.en }} (or .es, .fr, etc.). For multi-language apps, branch on {{ user.language }} to pick the matching key. The same applies to {{ message.data }} and {{ message.custom_data }}; use {{ message.data.key }} to reference a specific field.

object

The push or SMS message content (clipped at 50 characters). Email contents (email_body) are not provided. Set via the dashboard or the API contents property. Liquid: {{ message.contents }}

string

The template ID for a message sent via Journeys or the API template_id property. Liquid: {{ message.template_id }}

string

The message’s launch URL when using a single URL that is web and app agnostic. See URLs, Links and Deep Links. Liquid: {{ message.url }}

string

The app-specific launch URL when using separate web and app URLs. See URLs, Links and Deep Links. Liquid: {{ message.app_url }}

string

The web-specific launch URL when using separate web and app URLs. See URLs, Links and Deep Links. Liquid: {{ message.web_url }}

object

Custom key-value pairs from the data property on the notification, set via the dashboard or the API data property. Limited to one level of JSON. Use {{ message.data }} to return all properties, or {{ message.data.key }} for a specific key.

object

Custom key-value pairs from the custom_data property on the notification (API only). Supports multiple levels of JSON. Use {{ message.custom_data }} to return all properties, or {{ message.custom_data.key }} for a specific key.

string

The Live Activity action type: start, update, or end. Only present for message.live_activity.* events. Liquid: {{ message.live_activity_event_kind }}

Example message object

Copy this Liquid template into your Event Stream body to capture all message fields:

JSON

{
  "message.id": "{{ message.id }}",
  "message.name": "{{ message.name }}",
  "message.title": "{{ message.title }}",
  "message.contents": "{{ message.contents }}",
  "message.template_id": "{{ message.template_id }}",
  "message.url": "{{ message.url }}",
  "message.app_url": "{{ message.app_url }}",
  "message.web_url": "{{ message.web_url }}",
  "message.data": "{{ message.data }}",
  "message.custom_data": "{{ message.custom_data }}"
}

Example rendered output

A push notification message:

JSON

{
  "message.id": "f3c9cd09-10d7-4f59-b9bc-66e16607f1d5",
  "message.name": "weekly-promo-push",
  "message.title": "{'en':'Flash Sale: 50% Off Today'}",
  "message.contents": "{'en':'Shop now and save on select items'}",
  "message.template_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message.url": "https://example.com/sale",
  "message.app_url": "",
  "message.web_url": "",
  "message.data": "{'url': 'https://example.com/sale'}",
  "message.custom_data": "{}"
}

An email message. message.title is the subject line as a plain string, and message.contents is empty because email body content is not included in Event Stream data:

JSON

{
  "message.id": "e2d3c4b5-a6f7-8901-bcde-f12345678901",
  "message.name": "onboarding-welcome-email",
  "message.title": "Welcome to Acme: here's how to get started",
  "message.contents": "",
  "message.template_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "message.url": "",
  "message.app_url": "",
  "message.web_url": "",
  "message.data": "{}",
  "message.custom_data": "{}"
}

`user` properties

The user object contains profile-level data for the user who received the message.

string

The user’s OneSignal ID. Liquid: {{ user.onesignal_id }}

string

The user’s External ID. Liquid: {{ user.external_id }}

object

The user’s tags. Access the full object with {{ user.tags }} or a specific tag with {{ user.tags.your_tag }}. Use a default to handle missing tags: {{ user.tags.your_tag | default: '' }}.If you send dozens of tags per user, dumping the entire {{ user.tags }} object into every webhook body can push payloads past the receiver’s size limit (most platforms cap inbound webhooks at 1–2 MB). Reference only the specific tags you need ({{ user.tags.subscription_status }}, {{ user.tags.loyalty_tier }}, etc.) rather than the whole object.

string

The user’s language code. Liquid: {{ user.language }}

Email addresses and phone numbers aren’t on user.*. Email and phone are stored as subscriptions, not user attributes. To reference the recipient address from an event, use user.subscription.subscription_token. For email subscriptions this is the email address; for SMS subscriptions it is the phone number in E.164 format.

Example user object

Copy this Liquid template into your Event Stream body to capture all user fields:

JSON

{
  "user.onesignal_id": "{{ user.onesignal_id }}",
  "user.external_id": "{{ user.external_id }}",
  "user.language": "{{ user.language }}",
  "user.tags.loyalty_tier": "{{ user.tags.loyalty_tier | default: '' }}",
  "user.tags.subscription_status": "{{ user.tags.subscription_status | default: '' }}"
}

Example rendered output

JSON

{
  "user.onesignal_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "user.external_id": "user_12345",
  "user.language": "en",
  "user.tags.loyalty_tier": "gold",
  "user.tags.subscription_status": "active"
}

Reference tags individually with {{ user.tags.your_tag_key }} rather than dumping the whole {{ user.tags }} object into the payload.

`user.subscription` properties

These properties describe the subscription that received the message.

string

The subscription’s OneSignal ID. Liquid: {{ user.subscription.id }}

string

The OneSignal App ID. Liquid: {{ user.subscription.app_id }}

string

The subscription’s platform-specific token. For Email, this is the email address. For SMS, a phone number in E.164 format. For Push, the push token. Liquid: {{ user.subscription.subscription_token }}

number

Total sessions recorded for this subscription. Liquid: {{ user.subscription.session_count }}

string

The language code set on the subscription. Liquid: {{ user.subscription.language }}

string

The app or game version reported by the subscription (e.g., "4.12.0"). The game_version name is legacy from OneSignal’s gaming-app origins. It returns your app’s version regardless of category. Liquid: {{ user.subscription.game_version }}

number

UNIX timestamp of the subscription’s most recent session. Liquid: {{ user.subscription.last_active }}

number

Total session time recorded for this subscription, in seconds. Liquid: {{ user.subscription.play_time }}

number

UNIX timestamp of when the subscription was created. Liquid: {{ user.subscription.created_at }}

boolean

Whether the subscription is currently opted in to receiving messages. Liquid: {{ user.subscription.subscribed }}

string

The OneSignal SDK version on the subscription’s device. Liquid: {{ user.subscription.sdk }}

string

The device hardware model (e.g., “iPhone14,2”, “Pixel 7”). Liquid: {{ user.subscription.device_model }}

string

The device operating system and version (e.g., “iOS 17.2”, “Android 14”). Liquid: {{ user.subscription.device_os }}

Example user.subscription object

Copy this Liquid template into your Event Stream body to capture all subscription fields:

JSON

{
  "user.subscription.id": "{{ user.subscription.id }}",
  "user.subscription.app_id": "{{ user.subscription.app_id }}",
  "user.subscription.subscription_token": "{{ user.subscription.subscription_token }}",
  "user.subscription.session_count": "{{ user.subscription.session_count }}",
  "user.subscription.language": "{{ user.subscription.language }}",
  "user.subscription.game_version": "{{ user.subscription.game_version }}",
  "user.subscription.last_active": "{{ user.subscription.last_active }}",
  "user.subscription.play_time": "{{ user.subscription.play_time }}",
  "user.subscription.created_at": "{{ user.subscription.created_at }}",
  "user.subscription.subscribed": "{{ user.subscription.subscribed }}",
  "user.subscription.sdk": "{{ user.subscription.sdk }}",
  "user.subscription.device_model": "{{ user.subscription.device_model }}",
  "user.subscription.device_os": "{{ user.subscription.device_os }}"
}

Example rendered output

An iOS push subscription:

JSON

{
  "user.subscription.id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "user.subscription.app_id": "your-onesignal-app-id",
  "user.subscription.subscription_token": "abcd1234efgh5678ijkl9012mnop3456qrst7890uvwx1234yzab5678cdef9012",
  "user.subscription.session_count": "42",
  "user.subscription.language": "en",
  "user.subscription.game_version": "4.12.0",
  "user.subscription.last_active": "1708559115",
  "user.subscription.play_time": "18420",
  "user.subscription.created_at": "1690000000",
  "user.subscription.subscribed": "true",
  "user.subscription.sdk": "050216",
  "user.subscription.device_model": "iPhone14,2",
  "user.subscription.device_os": "iOS 17.2"
}

For an email subscription, subscription_token is the email address; for SMS, it is the phone number in E.164 format. Device fields (device_model, device_os, sdk, game_version, session_count, play_time) render as empty strings for email and SMS subscriptions.

FAQ

Why is some event data missing or blank?

Message data for Journeys and API sends is retained for 30 days. If a user interacts with a message (click, open, unsubscribe) more than 30 days after it was sent, the associated message properties may be blank. To work around this, correlate the message.id from the interaction event with the original sent event, which contains the full message data.

Why don’t I see `message.push.received` events?

message.push.received only fires when Confirmed receipt is enabled for your app. Without confirmed receipt, OneSignal cannot detect when a push notification reaches the device, so no received events are emitted. Enable confirmed receipt in your app settings before wiring downstream systems to this event.

Which `event.data.*` fields are populated for each event kind?

Only the fields that apply to the event kind are populated. All other event.data.* fields render as empty strings.

Event kind pattern	`event.data.*` fields populated
`message.iam.impression`	`page_name`, `page_id`
`message.iam.clicked`, `message.iam.page_displayed`	`page_name`, `page_id`, `target_name`, `target_id`
`message.live_activity.*`	`live_activity_id`, `live_activity_type`
`message.push.failed`, `message.email.failed`	`failure_reason`
All other event kinds	none

What is the difference between `event.id` and `message.id`?

event.id is a unique identifier for the individual event (e.g., one specific click). message.id is the identifier for the message that was sent. Multiple events can share the same message.id (for example, a sent event and a clicked event for the same push notification).

What format is `message.title` for push vs email?

For push notifications, message.title returns a localized object like {'en':'Your title'}. For email, it returns the subject line as a plain string. The format depends on the channel. To get a clean string from a push event regardless of locale, access the language key directly: {{ message.title.en }}. Branch on {{ user.language }} if you support multiple languages.

Are Custom Events included in Event Streams?

No. Event Streams contain message events (sent, clicked, opened, bounced, etc.), not Custom Events. Custom Events are user actions you send into OneSignal. Event Streams export message delivery and engagement data out of OneSignal.

How do I reference a specific tag in my Event Stream body?

Use {{ user.tags.your_tag_key }} with the exact tag key. To avoid errors when a tag is not set, add a default: {{ user.tags.your_tag_key | default: '' }}. See Using Liquid syntax for more details.

Event Streams

Set up and configure Event Streams, including setup, body templates, and debugging.

Using Liquid syntax

Reference for Liquid syntax used to personalize Event Stream bodies.

In-app message Event Streams

Details on in-app message event data and carousel tracking.

Metrics Glossary

Definitions for all message event metrics across channels.

First steps & settings

Message channels

Journeys

OneSignal AI

Audience & events

Analytics & Integrations

Privacy & Security

Event Stream data reference

`event` properties

Channel-specific fields

In-app message events

Live Activity events

Failed events

Event kind reference

Example event object

`message` properties

Example message object

`user` properties

Example user object

`user.subscription` properties

Example user.subscription object

FAQ

Why is some event data missing or blank?

Why don’t I see `message.push.received` events?

Which `event.data.*` fields are populated for each event kind?

What is the difference between `event.id` and `message.id`?

What format is `message.title` for push vs email?

Are Custom Events included in Event Streams?

How do I reference a specific tag in my Event Stream body?

Event Streams

Using Liquid syntax

In-app message Event Streams

Metrics Glossary

​event properties

​Channel-specific fields

​In-app message events

​Live Activity events

​Failed events

​Event kind reference

​Example event object

​message properties

​Example message object

​user properties

​Example user object

​user.subscription properties

​Example user.subscription object

​FAQ

​Why is some event data missing or blank?

​Why don’t I see message.push.received events?

​Which event.data.* fields are populated for each event kind?

​What is the difference between event.id and message.id?

​What format is message.title for push vs email?

​Are Custom Events included in Event Streams?

​How do I reference a specific tag in my Event Stream body?

​Related pages

Event Streams

Using Liquid syntax

In-app message Event Streams

Metrics Glossary

`event` properties

Channel-specific fields

In-app message events

Live Activity events

Failed events

Event kind reference

Example event object

`message` properties

Example message object

`user` properties

Example user object

`user.subscription` properties

Example user.subscription object

FAQ

Why is some event data missing or blank?

Why don’t I see `message.push.received` events?

Which `event.data.*` fields are populated for each event kind?

What is the difference between `event.id` and `message.id`?

What format is `message.title` for push vs email?

Are Custom Events included in Event Streams?

How do I reference a specific tag in my Event Stream body?

Related pages