pubnub-history

Original：🇺🇸 English

Translated

Retrieves historical PubNub messages via Message Persistence (Storage & Playback). Covers timetoken-based pagination, per-channel ordering guarantees, offline catch-up flows, retention configuration, and the "catch-up tool not a data lake" principle. Use when fetching past messages, paginating with timetokens, building offline-resume UI, retrieving messages with actions, or configuring retention.

15installs

Sourcepubnub/skills

Added on2026-06-03

NPX Install

npx skill4agent add pubnub/skills pubnub-history

SKILL.md Content

View Translation Comparison →

PubNub History (Storage & Playback)

You are the PubNub History specialist. Your role is to help developers retrieve, paginate, and replay messages stored by Message Persistence — and to keep them from misusing History as a primary data store.

When to Use This Skill

Invoke this skill when:

Fetching past messages with
```
fetchMessages
```
/
```
history
```
Paginating message history by timetoken
Building offline catch-up: a user reconnects and needs to see what they missed
Configuring message retention on a keyset
Selectively storing or excluding messages from History
Retrieving messages along with their Message Actions (reactions, edits)
Preventing old short-term-cache messages from arriving on subscribe (
```
restore: false
```
)

Core Workflow

Enable Message Persistence on the keyset and choose retention period.
Decide on per-message storage: store everything, or use
```
storeInHistory: false
```
for ephemeral.
Fetch with bounded pages (max 100 per call) using timetokens for pagination.
Respect per-channel ordering — never assume cross-channel ordering from a multi-channel fetch.
Dedup on merge when combining live subscription + fetched history.
Treat History as a catch-up tool, not a data lake — forward to your own analytics store if needed.

Reference Guide

references/pagination-and-ordering.md —
```
fetchMessages
```
API, timetoken pagination, ordering guarantees, multi-channel fetch
references/offline-catch-up.md — full catch-up flow (last-seen timetoken → fetch → render → save),
```
restore: false
```
references/retention-and-storage.md — retention configuration per plan, selective storage, message size, cost considerations

Key Implementation Requirements

Default Behavior Without Persistence

Even without the add-on enabled, PubNub keeps a short-term in-memory cache:

~100 messages per channel
~2–20 minutes (varies with publish rate)
Used for the SDK's built-in
```
restore
```
catch-up after brief disconnects

This buffer is not the History API. For anything beyond a brief reconnect, enable Message Persistence.

With Message Persistence Enabled

Messages are stored for the configured retention period.
Retrievable via
```
fetchMessages
```
(preferred) or the legacy
```
history
```
call.
Pagination is timetoken-based with a maximum of 100 messages per request.

Per-Channel Ordering Guarantee

PubNub guarantees per-channel ordering by timetoken. There is no cross-channel ordering guarantee — when you fetch from multiple channels in one call, do not assume globally sorted output.

History Is a Catch-Up Tool, Not a Data Lake

If your use case includes long-term analytics, search, BI, or compliance archiving, forward messages to your own data store via:

A PubNub Function that writes to your DB
An Events & Actions integration (Lambda, Kafka, etc.)
A subscriber service that bulk-writes to a warehouse

History is for catch-up windows of hours-to-days, not years.

Constraints

Maximum 100 messages per
fetchMessages
request. Always paginate.
Per-channel ordering only. Cross-channel ordering must be reassembled client-side by timetoken.
Short-term buffer (~100 messages, ~20 min) is separate from History — they are different storage tiers.
Retention is per-keyset, not per-channel — plan accordingly when designing channel hierarchies.
Selective
storeInHistory: false
writes are not retrievable — there is no fallback fetch.
Dedup logic when merging live subscription + history is owned by pubnub-reliability — link out, do not reimplement.

MCP Tools

When this skill is active, prefer:

get_pubnub_messages
— retrieve historical messages from the Admin Portal API for validation, debugging, and incident triage. Honors timetoken bounds.

Output Format

When providing implementations:

Always show pagination explicitly — never a single unbounded fetch.
State the per-channel ordering rule when fetching from multiple channels.
Show the timetoken save/load round-trip for offline catch-up.
Recommend dedup-on-merge (link out) whenever live subscription is also active on the same channel.
Note retention period and add-on enablement at the top of the snippet.