---
source_url: https://www.pubnub.com/docs/general/events
title: Event Types
updated_at: 2026-06-19T11:35:45.394Z
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# Event Types

When users interact with your app — sending messages, subscribing to channels, uploading files, or updating their profile — PubNub generates events. Your subscribed SDK clients receive these events in real time through listener callbacks, so you can react without polling.

This page lists all client-side event types and the payload fields each one includes. For events processed server-side through webhooks or queues, see [Events & Actions](https://www.pubnub.com/docs/serverless/events-and-actions/events).

## Client-side events

Client-side events are delivered in real time to your subscribed SDK clients through listener callbacks. There are six event types, each with its own handler.

To set up listeners and subscribe, see [Receive Messages](https://www.pubnub.com/docs/general/messages/receive).

:::warning Entity-enabled SDKs
Not all PubNub SDKs support entity-based subscriptions yet. For SDKs that still use the legacy listener API, refer to their [SDK API docs](https://www.pubnub.com/docs/sdks).
:::

:::note User ID / UUID
User ID is also referred to as **UUID/uuid** in some APIs and server responses but **holds the value** of the **userId** parameter you [set during initialization](https://www.pubnub.com/docs/general/setup/users-and-devices#set-the-user-id).
:::

### Message

PubNub sends this event when a message is published to a subscribed channel.

| Field | Description |
| --- | --- |
| `channel` | Channel on which the message was published |
| `subscription` | Channel group or wildcard subscription match, if any |
| `timetoken` | Publish timetoken |
| `message` | Message payload |
| `publisher` | User ID of the message publisher |

The `onMessage` handler receives this event. See [Publish Messages](https://www.pubnub.com/docs/general/messages/publish).

### Signal

PubNub sends this event when a signal is sent to a subscribed channel. Signals are lightweight, one-way notifications limited to 64 bytes — use them for high-frequency, low-cost updates like typing indicators or location pings. Unlike messages, signals do not support Message Persistence or Mobile Push Notifications.

| Field | Description |
| --- | --- |
| `channel` | Channel to which the signal belongs |
| `subscription` | Channel group or wildcard subscription match, if any |
| `timetoken` | Publish timetoken |
| `message` | Signal payload |
| `publisher` | User ID of the signal publisher |

The `onSignal` handler receives this event. See [Send Signals](https://www.pubnub.com/docs/general/messages/publish#send-signals).

### Presence

PubNub sends this event when a user's presence on a subscribed channel changes. Requires subscribing with the `receivePresenceEvents` option and Presence enabled on your keyset.

There are five presence event types:

| Event type | Emitted when |
| --- | --- |
| `join` | A user subscribes to the channel |
| `leave` | A user unsubscribes from the channel |
| `timeout` | A user is inactive for longer than the configured `presenceTimeout` |
| `state-change` | A user's presence state changes |
| `interval` | The channel is in interval mode and reports occupancy at a set interval |

Each presence event includes the following fields:

| Field | Description |
| --- | --- |
| `action` | Presence event type: `join`, `leave`, `timeout`, `state-change`, or `interval` |
| `channel` | Channel on which the presence change happened |
| `occupancy` | Total number of subscribers on the channel when the event occurred |
| `uuid` | User ID of the client whose presence changed |
| `timetoken` | Timetoken when the presence change took place |
| `data` | User state at the time of the event (present on `state-change` events) |
| `subscription` | Channel group or wildcard subscription pattern, if applicable |

:::note Interval mode
In `interval` mode, the `uuid` field is not present. Instead, the event may include `join`, `leave`, and `timeout` arrays (deltas) listing user IDs that changed since the last interval. See [Presence Events](https://www.pubnub.com/docs/general/presence/presence-events) for details on announce vs. interval mode.
:::

The `onPresence` handler receives this event. For event modes (announce vs. interval), presence deltas, heartbeat configuration, and JSON payload examples, see [Presence Events](https://www.pubnub.com/docs/general/presence/presence-events).

### App Context

App Context lets you store metadata for users, channels, and memberships directly on the PubNub platform. PubNub sends this event when that metadata is created, updated, or removed, so your app can stay in sync without polling.

| Field | Description |
| --- | --- |
| `channel` | Channel to which the event belongs |
| `subscription` | Channel group or wildcard subscription match, if any |
| `timetoken` | Event timetoken |
| `publisher` | User ID that triggered the change |
| `event` | Event type: `set` or `delete` |
| `type` | Entity type that changed: `uuid`, `channel`, or `membership` |
| `data` | Updated metadata for the entity |

The `onObjects` handler receives this event. See [App Context](https://www.pubnub.com/docs/general/metadata/basics).

### Message Action

PubNub sends this event when a message action is added to or removed from a message on a subscribed channel. Message actions are used for read receipts, delivery receipts, and emoji reactions.

| Field | Description |
| --- | --- |
| `channel` | Channel on which the message was published |
| `publisher` | User ID that added or removed the action |
| `event` | Action event type: `added` or `removed` |
| `data.type` | Message action type (for example, `reaction`) |
| `data.value` | Message action value (for example, an emoji string) |
| `data.messageTimetoken` | Timetoken of the message the action was applied to |
| `data.actionTimetoken` | Timetoken of the message action itself |

The `onMessageAction` handler receives this event. See [Message Actions](https://www.pubnub.com/docs/general/messages/actions).

### File

PubNub sends this event when a file is uploaded to a subscribed channel. Use file sharing to send images, documents, or videos — up to 5 MB per file — alongside your messages.

| Field | Description |
| --- | --- |
| `channel` | Channel to which the file was uploaded |
| `subscription` | Channel group or wildcard subscription match, if any |
| `publisher` | User ID of the file uploader |
| `timetoken` | Event timetoken |
| `message` | Optional message attached to the file |
| `file.id` | Unique file identifier |
| `file.name` | File name |
| `file.url` | Direct URL to download the file |

The `onFile` handler receives this event. See [File Sharing](https://www.pubnub.com/docs/general/files).

### Connection status

Connection status events are emitted on the PubNub client object, not on individual subscriptions. They report changes to the subscription connection state.

| Status | Emitted when |
| --- | --- |
| `PNConnectedCategory` | The subscription is started and the client is ready to receive real-time updates |
| `PNDisconnectedCategory` | The client intentionally disconnects |
| `PNDisconnectedUnexpectedlyCategory` | The client loses its connection unexpectedly |
| `PNConnectionErrorCategory` | The client cannot establish or re-establish the connection |
| `PNSubscriptionChangedCategory` | The mix of subscribed channels or channel groups changes after the initial connection |

Each connection status event includes the following fields:

| Field | Description |
| --- | --- |
| `category` | Status category name (for example, `PNConnectedCategory`) |
| `operation` | The operation that triggered the status (for example, `PNSubscribeOperation`) |
| `affectedChannels` | Channels affected by the status change |
| `subscribedChannels` | All currently subscribed channels |
| `affectedChannelGroups` | Channel groups affected by the status change |
| `lastTimetoken` | Previous subscription timetoken |
| `currentTimetoken` | Current subscription timetoken |

:::note SDK differences
Not all SDKs emit all of the statuses listed above, and some may present them differently. Consult your [SDK's status events documentation](https://www.pubnub.com/docs/sdks) for more information.
:::

The `status` handler on the `pubnub` object receives these events. For reconnection policies and full per-SDK status category references, see [Connection Management](https://www.pubnub.com/docs/general/setup/connection-management) and the [status events page for your SDK](https://www.pubnub.com/docs/sdks).

## Server-side events

Events & Actions (E&A) tracks PubNub platform events and lets you trigger actions — such as webhooks, SQS queues, or Kinesis streams — when they occur. You configure listeners in the Admin Portal. For event payload schemas, filter options, and setup instructions, see [Event / Action List](https://www.pubnub.com/docs/serverless/events-and-actions/events).

| Event source | Event types |
| --- | --- |
| Messages | Message sent; message reaction created; message reaction deleted; file sent |
| Users | User state changed; user created; user updated; user deleted |
| Channels | User started subscription; user stopped subscription; user timed out; first user subscribed; last user left; interval occupancy counted; channel created; channel updated; channel deleted |
| Mobile Push | Device removed; push error |
| Memberships | Membership created; membership updated; membership deleted |

## Terms in this document

* **PubNub** - PubNub is a real-time messaging platform that provides APIs and SDKs for building scalable applications. It handles the complex infrastructure of real-time communication, including: Message delivery and persistence, Presence detection, Access control, Push notifications, File sharing, Serverless processing with Functions and Events & Actions, Analytics and monitoring with BizOps Workspace, AI-powered insights with Illuminate.