Documentation Release Notes - August 2026
August made the documentation more precise about how PubNub delivers messages, added a dedicated Presence Occupancy page, and simplified the React Native setup for JavaScript SDK 12.0.0.
The main theme is message delivery guarantees. Message ordering, delivery semantics, recovery after a disconnect, and the subscribe transport now each have a precise description, so you can see what PubNub guarantees and what your application adds on top.
On the presence side, the new Presence Occupancy page covers count-only requests and member list pagination for large channels. It explains the limit and offset parameters we documented for HereNow in November 2025. For the JavaScript SDK, React Native setup is now one install command, following the JavaScript SDK 12.0.0 changes in June.
General 🛠️
Message delivery guarantees
Type: Enhancement
We rewrote how the documentation describes message delivery. The pages now answer one question consistently: what does PubNub guarantee, and what do you add yourself?
| Guarantee | What PubNub provides | What you add |
|---|---|---|
| At-most-once | Default for live delivery. A subscriber on a clean connection never receives a duplicate. | Nothing. Messages can be missed if the subscriber's buffer overflows or the client is disconnected at publish time. |
| At-least-once | Server-assigned timetokens and Message Persistence. | Track the timetoken of the last message you processed and replay history from it after a gap. On the REST API, qos=1 is an alternative for currently connected subscribers. |
| Exactly-once processing | No deduplication across publishes. | An idempotency key in the payload and deduplication on the receiving side. |
Message ordering
PubNub assigns each message a monotonically increasing timetoken, so messages on a channel form a single ordered sequence. Subscribers receive them in that order, and messages you retrieve later from Message Persistence keep it. You don't need a sequence field in the payload. The previous text said messages are "typically" kept in order and suggested adding your own sequence field for strict ordering. The real risk is message loss when a subscriber falls behind, not reordering. The Message ordering section now says so.
Delivery semantics
The new Delivery semantics section covers three points that were not documented before:
- Publishing the same payload twice always creates two messages with two timetokens. PubNub doesn't deduplicate publishes on the server.
- By default, SDKs retry subscribe operations but not publish or signal calls, though this varies by SDK. Treat a retried publish as a new message and design consumers to tolerate an occasional duplicate.
- Some SDKs deduplicate on the subscribe side. This is automatic in the Swift SDK and configurable with
dedupOnSubscribein the C#, Java, Kotlin, and Unity SDKs. It suppresses redelivery of one message, so it doesn't replace an idempotency key.
qos is available only on the REST API
The REST publish API accepts a qos parameter. Setting it to 1 makes the publish call wait until the message is in each connected subscriber's receive buffer. If delivery fails, the call returns an error and you can safely retry it. Each retry creates a new, distinct message. No PubNub SDK exposes qos. For details, see At-least-once delivery with qos.
To replay history from the last message you processed, pass a timetoken one greater than it as end. The end boundary is inclusive, so passing the timetoken itself fetches that message again. Timetokens are 17-digit values that exceed Number.MAX_SAFE_INTEGER, so use BigInt rather than plain addition.
1// Timetoken of the last message your app processed (example value)
2const lastReceived = '17000000000000000';
3
4// end is inclusive, so ask for the timetoken right after it
5const end = (BigInt(lastReceived) + 1n).toString();
6
7const response = await pubnub.fetchMessages({
8 channels: ['my_channel'],
9 end,
10});
A single call returns up to 100 messages for one channel, or 25 per channel across multiple channels, so keep paging until you reach your last known message.
Recovering after a disconnect
The Connection management page now separates two independent recovery mechanisms:
- Buffer replay is automatic. After a reconnect, the SDK resumes from the last timetoken it received and PubNub replays what the subscriber message buffer still holds. By default the buffer holds 100 messages for up to 16 minutes and drops the oldest first. PubNub Support can provision a larger buffer, for example 300 or 500 messages.
- History replay is manual. For longer outages or bursts, fetch the gap from Message Persistence. It only recovers messages that were stored, so it can't return signals, messages published with
storeInHistoryorshouldStoreset tofalse, or messages whose per-messagettlhas expired.
One does not fall back to the other. Choose based on how long the client was disconnected and how many messages your channels publish in that window. When you save the timetoken to replay from, save the last one you received before the gap, not the one your listener reports after automatic catch-up, because catch-up advances the cursor past the gap.
Subscribe transport
The Data transport and delivery page now describes how subscribe works: SDKs hold an HTTP request open, receive messages as its response, and resume from a timetoken cursor on the next request. It also explains why PubNub doesn't use WebSocket: long polling uses ordinary HTTP, so it passes through proxies, CDNs, load balancers, and firewalls without connection-upgrade failures. Delivery guarantees come from timetokens and Message Persistence, not from the transport, so they hold regardless of it.
Presence Occupancy
Type: New feature
We published a Presence Occupancy page for the Here Now API. It covers what a Here Now response contains, how to request only the count, and what changes on channels with many subscribers.
For a channel with many users, request the count without the member list. The response size stays constant however many clients are on the channel:
1const response = await pubnub.hereNow({
2 channels: ['my_channel'],
3 includeUUIDs: false,
4});
When you do need the member list, Here Now returns up to 1,000 occupants per channel per call. Use offset to page through the rest. The occupancy count isn't subject to that limit and always reflects the true number of subscribers:
1// First 100 occupants
2await pubnub.hereNow({ channels: ['my_channel'], limit: 100 });
3
4// Next 100 occupants
5await pubnub.hereNow({ channels: ['my_channel'], limit: 100, offset: 100 });
The page also explains what happens above the Announce Max threshold. PubNub stops sending individual join, leave, and timeout events and sends periodic interval events instead. Presence webhooks aren't sent for those channels, so use Here Now or interval events to track occupancy on them.
In the Presence documentation we also noted that some SDKs derive the heartbeat interval from presenceTimeout once you set it. That can generate more API calls than you expect, so check your SDK's configuration reference before relying on the default.
SDKs 📦
React Native setup for JavaScript SDK 12.0.0
Type: Enhancement
JavaScript SDK 12.0.0 stopped bundling react-native-url-polyfill, so React Native projects have to install it. We updated the JavaScript SDK documentation to show that installing it is the only step. Previously, the docs sent you to the polyfill's own setup instructions to apply it in your app entry point.
npm install pubnub react-native-url-polyfill
Once the package is installed, the SDK applies the polyfill automatically, with no extra import or setup. Without the package, React Native apps that depend on the URL global can fail at runtime. The change appears in Set up your environment and the JavaScript SDK 12.0.0 migration guide.