History and snapshots

Realtime stores room and channel history so clients can replay recent activity, catch up after reconnecting, and load older messages.

Write messages to history

publish() and broadcast() record messages for the room or channel:

await live.room("project_123").publish({
  type: "comment.created",
  data: {
    commentId: "comment_123",
    body: "Looks good",
  },
  metadata: {
    source: "web",
  },
})

Use idempotencyKey when retries can submit the same message more than once:

await room.publish({
  type: "comment.created",
  data: comment,
  idempotencyKey: `comment:${comment.id}`,
})

Read history

const history = await live.room("project_123").history({
  limit: 50,
})

History items include the message ID, type, data, metadata, actor, and publish time.

Page through history

const firstPage = await room.history({ limit: 50 })

if (firstPage.cursor) {
  const older = await room.history({
    limit: 50,
    cursor: firstPage.cursor,
  })
}

Use pagination for chat logs, audit timelines, and reconnect catch-up.

Snapshot a room

Snapshots capture room state at a point in time:

const snapshot = await live.room("project_123").snapshot()

The snapshot result includes:

• snapshotId
• createdAt
• Room metadata
• Active members
• Recent messages

Store snapshotId when users create named versions or when background jobs checkpoint state.

Restore a snapshot

await live.room("project_123").restore(snapshot.snapshotId)

Use restore for collaborative documents, admin recovery, moderation workflows, and guided demos.

Configure default history size

const live = realtime({
  name: "live",
  historyLimit: 200,
})

Per-call limits can still be smaller:

await room.history({ limit: 25 })