---
source_url: https://www.pubnub.com/docs/architecture/events
title: Events
updated_at: 2026-09-30T07:20:08.000Z
---

# Events

## Documentation index

To discover more PubNub resources:

1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.

Do not assume a path exists, always check the index first.

PubNub generates an event every time something meaningful happens on the platform: a message is published, a user joins a channel, a file is uploaded, or a stored record changes. This page explains what produces an event, what an event carries, and the two places you can consume one.

A channel is an address, not a resource. PubNub delivers an event to every client subscribed to that address. Server-side handlers like [Events & Actions](https://www.pubnub.com/docs/integrations/event-forwarding/overview.md) observe events without subscribing at all.

## What every event carries

Every subscription-based event identifies the channel it arrived on and carries a [timetoken](https://www.pubnub.com/docs/architecture/core-concepts.md#timetoken). Most also carry the [User ID](https://www.pubnub.com/docs/architecture/core-concepts.md#user-id) of the client that triggered the event, so a subscriber can tell who acted without inspecting the payload.

The exact field set varies by event type, and three differences matter when you write a handler:

* A presence event names the acting client in a `uuid` field rather than in `publisher`.
* A Message Action event carries two timetokens, `data.messageTimetoken` and `data.actionTimetoken`, rather than one top-level timetoken, because it refers to a message published earlier.
* A connection status event has a different shape entirely. It reports the state of the SDK's connection, not an action on a channel, so it has no publisher and no channel of its own.

Field names and types are per-SDK rather than platform-wide. For the exact shape your handler receives, refer to the API reference for your platform in [Available SDKs](https://www.pubnub.com/docs/getting-started/available-sdks.md).

## Event types

| Event type | What triggers it | Prerequisites | Consumed via |
| --- | --- | --- | --- |
| Message | A message published to a channel | None | SDK listener; Events & Actions |
| Signal | A signal sent to a channel | None | SDK listener |
| Presence `join` / `leave` / `state-change` | A client subscribing, unsubscribing, or updating state | Presence add-on; `receivePresenceEvents` option | SDK listener |
| Presence `timeout` / `interval` | Heartbeat expiry or occupancy interval (server-generated) | Presence add-on; `receivePresenceEvents` option | SDK listener |
| App Context | User, channel, or membership record created, updated, or deleted | App Context enabled on keyset | SDK listener; Events & Actions |
| Message Action | A reaction or receipt added to or removed from a message | None | SDK listener |
| File | A file uploaded to a channel | File Sharing enabled on keyset | SDK listener; Events & Actions |
| Connection status | The SDK's own network connection state changes | None | SDK listener (status handler) |

## Client-side events

Events are pushed in real time to subscribed SDK clients through [event listeners](https://www.pubnub.com/docs/pub-sub/subscribe/event-listeners.md). Once a client subscribes to a channel or channel group, PubNub delivers matching events with no polling. Each event type has a dedicated handler. The exact handler name and registration method vary by SDK; refer to the API reference for your platform in [Available SDKs](https://www.pubnub.com/docs/getting-started/available-sdks.md).

In entity-based SDKs, you register handlers on a `Subscription` or `SubscriptionSet` built from a channel, channel group, or metadata entity. SDKs that predate entities register handlers on the PubNub client object, where they apply to every subscribed channel at once. Refer to [SDK entities](https://www.pubnub.com/docs/architecture/core-concepts.md#message).

### Message

A message event fires when a message is published to a subscribed channel. The payload is the JSON value the publisher sent. Messages can be stored by [Message Persistence](https://www.pubnub.com/docs/data-storage/message-history/overview.md) for retrieval later.

### Signal

A signal event fires when a signal is sent to a subscribed channel. Signals carry transient, high-frequency data such as typing indicators or cursor positions. Signal payloads are limited to 64 bytes. Unlike messages, signals are never stored and can't trigger mobile push notifications.

### Presence

A presence event fires when a client's connection state on a subscribed channel changes. Its five subtypes (`join`, `leave`, `timeout`, `state-change`, and `interval`) cover the whole lifecycle of a client's participation in a channel. Every presence event carries the channel's current occupancy and, except in interval mode, the [User ID](https://www.pubnub.com/docs/architecture/core-concepts.md#user-id) of the client whose state changed. For announce mode, interval mode, and heartbeat configuration, refer to [Presence events](https://www.pubnub.com/docs/presence/presence-events.md).

### App Context

An [App Context](https://www.pubnub.com/docs/data-storage/metadata/overview.md) event fires when user metadata, channel metadata, or a membership record is created, updated, or deleted. The payload names the entity type that changed (`uuid`, `channel`, or `membership`) and includes the updated record, so a client stays in sync without polling.

### Message Action

A [message action](https://www.pubnub.com/docs/pub-sub/message-actions/overview.md) event fires when an action such as an emoji reaction or a read receipt is added to or removed from a message on a subscribed channel. The payload references the original message by its timetoken and carries the action type and value.

### File

A file event fires when a file is uploaded to a subscribed channel. The payload carries the file ID, the file name, and a download URL, along with any text message attached to the upload. For more information, refer to [Files](https://www.pubnub.com/docs/data-storage/files/overview.md).

### Connection status

A connection status event reports a change in the state of the SDK's network connection. Status events are emitted on the PubNub client object rather than on an individual subscription, and you read them through a status handler.

They exist because a subscribe failure is otherwise invisible: a subscribe request that returns nothing looks exactly like a quiet channel. The categories describe whether the client connected, whether the channel mix changed, and whether a failure happened before or after a working connection. The literal category names belong to each SDK rather than to the platform.

For the categories, the difference between a connection that never established and one that dropped, and the reconnection policy behind both, refer to [Connection management](https://www.pubnub.com/docs/architecture/connection-management/overview.md#the-status-listener).

## Server-side events

[Events & Actions](https://www.pubnub.com/docs/integrations/event-forwarding/overview.md) is PubNub's server-side event processing layer. It observes the same platform actions that generate client-side events and triggers a response, such as a webhook call, an SQS message, or a Kinesis record. You don't need to deploy a consumer process. You configure the listeners and their actions in the [Admin Portal](https://admin.pubnub.com/).

Its event sources cover messages, including file uploads, plus users, channels, mobile push, and memberships.

Client-side and server-side events observe the same underlying actions but answer different needs. Client-side events drive real-time UI updates in a connected app, and a client only ever sees the channels it subscribed to. Events & Actions drives server-side workflows, integrations, and data pipelines, and it needs no subscription at all.

For the available sources and the shape of each forwarded payload, refer to [Event sources](https://www.pubnub.com/docs/integrations/event-forwarding/event-sources.md) and [Payloads](https://www.pubnub.com/docs/integrations/event-forwarding/payloads.md).

## Next steps

* [Event listeners](https://www.pubnub.com/docs/pub-sub/subscribe/event-listeners.md) - how a handler is registered and what its scope is.
* [Subscribe](https://www.pubnub.com/docs/pub-sub/subscribe/overview.md) - how a client chooses which channels its events come from.
* [Core concepts](https://www.pubnub.com/docs/architecture/core-concepts.md) - channels, messages, User IDs, timetokens, tokens, and memberships.
* [Connection management](https://www.pubnub.com/docs/architecture/connection-management/overview.md) - status events, reconnection policies, and missed-event recovery.

Last updated at: 2026-09-30T07:20:08.000Z