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.
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.
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.
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.
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.
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.
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 |
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 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.
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.
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.
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.
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 |
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 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 and the status events page for your SDK.
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.
| 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 |