Core concepts
PubNub is built on a small set of concepts that appear in every SDK method, REST endpoint, and platform feature. This page defines each one and points to the feature documentation that uses it.
One boundary applies to all of them: every concept below is scoped to a single keyset. A keyset is the set of publish, subscribe, and secret keys that identifies your application to the PubNub network. A channel, User ID, or membership created under one keyset can't be reached from another. That's what lets a development keyset and a production keyset carry the same channel names without ever meeting. To create a keyset, refer to Set up your account.
A client publishes a message to a channel, and PubNub assigns the message a timetoken. Each token belongs to one User ID. A membership links a User ID to a channel.
| Concept | What it is |
|---|---|
| Message | The unit of data published to a channel and delivered to subscribers |
| Channel | The named pathway through which messages flow |
| User ID | The unique identity of a connected client |
| Timetoken | The server-assigned timestamp that's the ordering key for events on a channel |
| Token | The signed credential that controls access to PubNub resources |
| Membership | The persistent record of which User ID belongs to which channel |
Message
A message is the basic unit of data flowing through PubNub, and its payload is any JSON-serializable value. When a client publishes to a channel, PubNub delivers the payload to every subscriber of that channel in real time, and PubNub SDKs serialize the payload for you.
PubNub carries two publish types:
- A message is the general-purpose unit, optionally stored by Message Persistence so it can be retrieved later. The standard message payload size limit is 32 KiB. This includes the channel name and any metadata.
- A signal is a deliberately smaller unit for high-frequency, transient updates such as typing indicators or cursor positions. Signal payloads are limited to 64 bytes. Signals are never stored and can't trigger mobile push notifications.
You can assign a custom message type to any publish to categorize and filter traffic on a channel without inspecting individual payloads.
Every message carries the publisher's User ID and a server-assigned timetoken. Messages are not the only thing a subscription delivers. File uploads arrive as file events, App Context changes arrive as metadata events, message actions arrive as their own events, and presence events arrive on -pnpres companion channels. Each type has its own listener handler.
For the publish and subscribe model that carries all of these, refer to Pub/Sub. For the complete event list, refer to Events.
Modern PubNub SDKs represent channels, channel groups, and metadata records as typed entity objects: Channel, ChannelGroup, UserMetadata, ChannelMetadata. Each entity provides a typed API scoped to that resource: calling .subscription() on a Channel creates a subscription scoped to that channel; calling .subscription() on a ChannelGroup creates one scoped to every channel in the group. SDKs that predate entities register listeners on the PubNub client object instead, where handlers apply to all subscribed channels at once. Not every SDK supports entities. Check the API reference for your platform in Available SDKs.
Channel
A channel is a named pathway through which clients exchange messages. Publishers send to a channel, and subscribers on the same channel receive those messages in real time. The channel name is the entire address. PubNub routes a message published to a channel to every client currently subscribed to that same channel, and to nobody else.
A channel is a name, not a resource you declare. Channels are created implicitly the first time they are used and do not require provisioning, so your channel naming scheme is a design decision rather than a provisioning task, and an application can invent names at runtime.
A single SDK connection can subscribe to many channels at once. A period in a channel name, as in chat.room.123, gives the name a hierarchy, so a wildcard subscription such as chat.* receives every channel matching the pattern.
PubNub channel names are case-sensitive. Channel names cannot exceed 92 UTF-8 characters. For the full naming grammar, the characters a name may contain, and the conventions that make a name addressable by a pattern, refer to Channels and channel naming.
Presence, once enabled on your keyset, gives each subscribed channel a -pnpres companion channel that carries join, leave, and timeout events for it.
You can attach persistent metadata to any channel using App Context, including display name, description, type, and custom fields.
A channel group is a server-managed list of channels a client can subscribe to as a single unit, useful when the set of channels needs to change without the client resubscribing.
User ID
A User ID is the string that identifies a single connected client, whether that client is a person, a device, or a server process. You set it during SDK initialization, and PubNub uses it across the entire platform. A User ID cannot exceed 92 UTF-8 characters.
A User ID serves three distinct roles:
- Billing. The User ID is the Monthly Active User (MAU) billing anchor. Reuse the same value across sessions for the same person, or one person is counted as several MAUs.
- Presence. Every join, leave, timeout, and state-change event includes the User ID of the affected client.
- Access control. Access Manager tokens are bound to an
authorized_uuid, so only the client whose User ID matches can use the token.
The User ID may be visible to other clients. Don't use an email address, a username, or any other personally identifiable information as a User ID. Use a non-identifiable value you can revoke and replace without the user having to act.
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.
You can attach persistent structured metadata to any User ID using App Context, including name, email, profile URL, and custom fields.
For how identity relates to authentication and authorization, refer to Authentication and authorization.
Timetoken
A timetoken is the timestamp PubNub assigns server-side to every event a subscription delivers: messages, presence changes, file uploads, metadata updates, and message actions. PubNub assigns every published message a server-side timetoken: a monotonically increasing 17-digit value precise to 100 nanoseconds (10⁻⁷ s), the number of 100-nanosecond intervals since the Unix epoch. A timetoken identifies that message on that channel afterwards.
PubNub assigns every message a server-side timetoken when it accepts the publish. The timetoken records when PubNub accepted the message, which can differ from when the client sent it. History fetched through Message Persistence returns a channel's messages in timetoken order.
A subscriber receives live messages in the order they reach it, and each message carries its timetoken. Arrival order can differ from timetoken order and from one subscriber to another. Sorting a channel's messages by timetoken gives every client the same order. Timetoken order applies within a channel, so each channel's messages sort on their own.
Timetokens appear throughout the platform:
| Where | How it is used |
|---|---|
| Subscribe cursor | The 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 the timetoken of when it occurred |
| Message actions | Reactions and read receipts reference the original message by its timetoken |
| Unread tracking | Membership stores a last-read timetoken per user per channel for unread count calculations |
A PubNub timetoken exceeds the largest integer a JavaScript Number represents exactly, so increment or compare timetokens with an arbitrary-precision integer type such as BigInt rather than with plain numeric arithmetic.
For how a timetoken drives recovery after a disconnect, refer to Connection management.
Token
An Access Manager token is a signed, time-limited access credential that your server generates with the secret key and passes to a client. It is the credential Access Manager checks. The client presents it on every PubNub operation, and PubNub validates it before executing the request.
Each token carries:
authorized_uuid. The User ID the token is bound to. Only the client whose User ID matches can use it.- TTL (Time To Live). The expiry, in minutes. Clients must refresh a token before it expires.
- Permissions. Scoped per resource type, covering read, write, delete, and manage operations on channels, channel groups, user metadata, channel metadata, and memberships. For the full model, refer to Access Manager permission model.
Without Access Manager enabled on your keyset, any client holding your publish and subscribe keys has unrestricted access to every channel and every stored record on that keyset. Enable Access Manager if your application needs private channels, per-user permissions, or handles sensitive data.
The secret key grants privileged access to your PubNub application. It must remain on a trusted server and must never be included in client applications.
Membership
A membership is the persistent record that a specific User ID belongs to a specific channel. PubNub stores a membership, so it survives disconnects and session restarts whether or not the user is online. Enable App Context on your keyset in the Admin Portal before creating or querying memberships.
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 rosters, unread counts | Live occupancy, join and leave events |
Use both together to build a member list that distinguishes online members from offline ones. A membership record also holds custom metadata and a last-read timetoken per channel, which is what unread message counts are calculated from.
Platform limits apply: up to 50,000 memberships per user and up to 5,000 members per channel.
Deleting a user or a channel doesn't remove their memberships unless referential integrity is enabled on your keyset in the Admin Portal. Otherwise a membership persists until you delete it explicitly.
Next steps
- Pub/Sub - how channels route data and what travels on one.
- Events - every event type PubNub generates and what each one carries.
- How PubNub works - the network that carries these concepts.
- API limits - the hard and soft limit for each concept on this page.