Events

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 observe events without subscribing at all.

What every event carries

Every subscription-based event identifies the channel it arrived on and carries a timetoken. Most also carry the 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.

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

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.

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 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 of the client whose state changed. For announce mode, interval mode, and heartbeat configuration, refer to Presence events.

App Context

An App Context 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 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.

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.

Server-side events

Events & Actions 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.

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 and Payloads.

Next steps

• Event listeners - how a handler is registered and what its scope is.
• Subscribe - how a client chooses which channels its events come from.
• Core concepts - channels, messages, User IDs, timetokens, tokens, and memberships.
• Connection management - status events, reconnection policies, and missed-event recovery.