Core PubNub Concepts

PubNub is built on seven primitives. Every SDK method, REST endpoint, and platform feature is an operation on one or more of them. Understanding these concepts upfront makes the rest of the platform easier to navigate.

Primitive	What it is
Message	The unit of data published to a channel and delivered to subscribers
Channel	The named pathway messages flow through
User ID	The unique identity of a connected client
Channel Group	A server-managed list of channels subscribed to as one unit
Timetoken	The server-assigned timestamp that orders every event
Token	The cryptographic credential that controls access to resources
Membership	The persistent record of which user belongs to which channel

Message

A message is the basic unit of data flowing through PubNub. When you publish to a channel, PubNub delivers the payload to every subscriber of that channel in real time. Messages are ephemeral in transit by default — enable Message Persistence to store and retrieve them later.

PubNub supports two publish types:

• Message — full-payload delivery, optionally persisted by Message Persistence.
• Signal — lightweight ephemeral payload (up to 64 bytes) for high-frequency updates like typing indicators or cursor positions. Signals are never stored.

You can assign a custom message type to any publish to categorize and filter traffic on a channel without inspecting individual payloads. Messages are the primary unit by which throughput is measured — signals cost less and are suited for high-frequency, non-critical updates.

Messages carry the publisher's User ID and a server-assigned timetoken and progress through a lifecycle: published, delivered in real time, and optionally persisted.

Several other event types are also delivered through the same message listener:

• File uploads arrive as a special file message type on the same channel.
• App Context change events — user metadata, channel metadata, and membership updates — are delivered as messages on channels.
• Presence events arrive as message-like payloads on -pnpres channels through the same delivery infrastructure.
• When a subscriber is offline, published messages can be converted into native push payloads and delivered via Mobile Push Notifications.

For more information, refer to Messages overview and Publish & subscribe.

Channel

A channel is a communication pathway for passing data between clients with PubNub. Channels are created implicitly the first time you publish to them — no provisioning required.

Key capabilities include:

• Wildcard subscribe (chat.*) lets a single subscription cover any channel matching the pattern.
• Channel groups bundle multiple channels behind one subscribe call (see Channel Group).
• A single SDK connection can multiplex subscriptions across multiple channels simultaneously.
• Channels are the most common Access Manager permission scope.
• Persistent metadata (name, description, type, custom fields) can be attached using App Context. When metadata changes, PubNub fires real-time events on the channel — enable this in the Admin Portal.
• Dot notation in channel names (e.g. chat.room.123) enables wildcard subscriptions and Functions routing patterns. Use consistent naming conventions — they directly affect how you apply permissions and process traffic at scale.
• Presence operates on channels. PubNub automatically creates a -pnpres companion channel for each subscribed channel to deliver real-time join, leave, and timeout events.
• Use HereNow to query current channel occupancy and WhereNow to query which channels a specific user is subscribed to.
• You can filter messages server-side by configuring filter expressions on a subscription, so subscribers only receive messages matching specific criteria.
• Events & Actions can trigger webhooks when a channel becomes active (first subscriber joins) or inactive (last subscriber leaves).

For more information, refer to Channel basics, Subscribe, and Channel naming.

User ID

A User ID (also referred to as UUID in some SDKs and API responses) is the unique string identifying a single connected client — a person, a device, or a server process. You set it during SDK initialization, and PubNub uses it across the entire platform.

User IDs drive three things across the platform:

• Billing — User IDs are the Monthly Active User (MAU) billing anchor. Reuse the same ID across sessions to avoid counting the same user multiple times.
• Presence — Every join, leave, timeout, and state-change event includes the User ID of the affected client.
• Security — Access Manager tokens are bound to an authorized_uuid. Only the client whose User ID matches can use the token.

User IDs also connect to other platform capabilities:

• You can attach persistent structured metadata — name, email, profile URL, and custom fields — to any User ID using App Context. PubNub fires real-time events when that metadata changes.
• You can grant scoped metadata permissions (get, update, delete) per User ID using Access Manager tokens.
• The publisher's User ID is stored alongside every message in Message Persistence, letting you attribute historical traffic to individual users.
• File messages include the uploader's User ID as the publisher.
• For Mobile Push Notifications, device tokens are registered to channels rather than User IDs directly — multi-device UUID sharing can affect presence behavior.

User ID confidentiality

The User ID may be visible to other clients. Don't use emails, usernames, or any personally identifiable information. Use a non-identifiable value you can revoke and replace without user action.

For more information, refer to Users & Devices.

Channel Group

A channel group is a server-managed, named list of channels that clients subscribe to with a single call. The server owns the membership of the group. When channels are added or removed server-side, all subscribed clients automatically start or stop receiving messages from those channels without resubscribing.

Key constraints include:

• Subscribe-only. You cannot publish directly to a channel group.
• Default limits: 10 groups per keyset, 1,000 channels per group (configurable up to 2,000).
• Requires the Stream Controller add-on enabled on your keyset.
• Token permissions for channel groups: read (subscribe, list channels) and manage (add/remove channels, delete group).
• Subscribing to a channel group also delivers aggregated presence events for all channels in the group.
• A channel group is created automatically when the first channel is added to it and deleted via API call.
• Group names cannot contain a period (.).
• You can list all channels in a group via the API.
• Channel groups are also available as SDK entities, providing object-oriented methods for subscription management.

For more information, refer to Channel groups.

Timetoken

A timetoken is a 17-digit nanosecond UTC timestamp assigned server-side by PubNub to every published event. Because PubNub assigns timetokens centrally in a single monotonic sequence, no two events on the same channel share a timetoken and no client needs to implement its own ordering logic.

Timetokens appear throughout the platform:

Where	How it's used
Subscribe cursor	Your SDK tracks the last received timetoken to resume from after a disconnect or app restart
History pagination	Pass start and end timetokens to fetch a specific window of messages from Message Persistence
Message counts	Query how many messages were published on a channel after a given timetoken
Presence events	Every join, leave, timeout, and state-change event includes a timetoken indicating when it occurred
Message actions	Message actions (reactions, receipts) reference the original message by its timetoken
Unread tracking	Membership metadata stores a "last read timetoken" per user per channel for unread count calculations
Functions context	The Before Publish function handler receives the publish timetoken. After Publish does not
App Context events	Metadata update events (user, channel, membership) include a timetoken indicating when the change occurred
File uploads	File uploads return a timetoken, used to identify file messages in history
Illuminate	PUBLISH_TIMETOKEN defines time ranges for Business Objects queries
Retention	Timetokens determine which messages fall within the retention window and are eligible for retrieval

For more information, refer to Message Persistence and Publish & subscribe.

Token

A token is the cryptographic access credential used by Access Manager (v3). It is a signed, time-limited object — not a JWT — generated on your server using your secret key and passed to clients. Clients set it as their authKey. PubNub validates it on every operation.

Token fields

Each token contains:

• authorized_uuid — the User ID this token is valid for. Only the client with a matching User ID can use it.
• TTL — expiry in minutes. Clients must refresh tokens before they expire. Revocation is available via the Admin Portal or API.

Permissions

Permissions are scoped per resource type:

Resource	Grantable operations
Channels	read (subscribe, HereNow, GetState, SetState), write (publish, signal), delete (messages)
Channel groups	read (subscribe, list channels), manage (add/remove channels, delete group)
User metadata (UUID)	get, update, delete
Channel metadata	get, update, delete
Memberships	manage, join
WhereNow	No permission required

You can name resources individually or use regex patterns to target a family of channels (e.g. chat\..+) without listing each one. The same token also governs access to stored messages (Message Persistence), files, and push notification channel registration.

Access Manager is optional (but recommended)

Without Access Manager enabled on your keyset, any client with your publish/subscribe keys has unrestricted access. Enable it when your app needs scoped, per-user permissions.

For more information, refer to Access Manager.

Membership

A membership is the persistent record that a specific User ID belongs to a specific channel. It is stored on PubNub's platform and survives disconnects and session restarts — independent of whether the user is currently online. PubNub fires real-time events when users are added to or removed from a channel, so you can react to membership changes the same way you react to messages.

Membership is the complement of Presence:

	Membership	Presence
Persistence	Permanent (until deleted)	Ephemeral (cleared on disconnect)
Answers	"Who belongs to this channel?"	"Who is online right now?"
Typical use	Member lists, channel lists, unread counts	Live occupancy, join/leave events

Use both together to build a complete member list that distinguishes online members from offline ones. Membership records also support custom metadata and store a "last read timetoken" per channel for calculating unread message counts.

Access control and limits

Setting and removing memberships requires a token with the join permission (channel-scoped) or update permission (UUID-scoped). Reading memberships requires get. Platform limits apply: up to 50,000 memberships per user and 5,000 members per channel.

Lifecycle

Memberships persist until explicitly deleted. By default, deleting a user or channel does not remove their memberships — orphan memberships can exist. You can enable referential integrity in the Admin Portal to automatically delete memberships when the related user or channel is deleted.

Integrations

Events & Actions can trigger webhooks or automations on membership changes. BizOps Workspace provides a UI to add, update, delete, view, and filter memberships directly from the Admin Portal. Illuminate Business Objects can map membership data for analytics, and decisions can trigger an Update Membership action (APPCONTEXT_SET_MEMBERSHIP_METADATA).

For more information, refer to Membership metadata.