+```javascript
+const claims = {
+ 'x-ably-clientId': 'user-123'
+};
+```
+
+
+The `clientId` is automatically attached to every message the user publishes, so agents can trust this identity.
+
+
+```javascript
+await channel.subscribe('user-input', (message) => {
+ const userId = message.clientId;
+ // promptId is a user-generated UUID for correlating responses
+ const { promptId, text } = message.data;
+
+ console.log(`Received prompt from user ${userId}`);
+ processAndRespond(channel, text, promptId, userId);
+});
+```
+
+
+### Verify by role
+
+Use [user claims](/docs/ai-transport/sessions-identity/identifying-users-and-agents#user-claims) to verify that a message comes from a user rather than another agent sharing the channel. This is useful when the agent needs to distinguish message sources without needing the specific user identity.
+
+When a user [authenticates with Ably](/docs/ai-transport/sessions-identity/identifying-users-and-agents#authenticating), embed their role in the JWT:
+
+
+```javascript
+const claims = {
+ 'ably.channel.*': 'user'
+};
+```
+
+
+The user claim is automatically attached to every message the user publishes, so agents can trust this role information.
+
+
+```javascript
+await channel.subscribe('user-input', (message) => {
+ const role = message.extras?.userClaim;
+ // promptId is a user-generated UUID for correlating responses
+ const { promptId, text } = message.data;
+
+ if (role !== 'user') {
+ console.log('Ignoring message from non-user');
+ return;
+ }
+
+ processAndRespond(channel, text, promptId);
+});
+```
+
+
+## Publish user input
+
+Users publish messages to the channel to send prompts to the agent. Generate a unique `promptId` for each message to correlate agent responses back to the original prompt.
+
+
+```javascript
+const channel = ably.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+const promptId = crypto.randomUUID();
+await channel.publish('user-input', {
+ promptId: promptId,
+ text: 'What is the weather like today?'
+});
+```
+
+
+
+
+## Subscribe to user input
+
+The agent subscribes to a channel to receive messages from users. When a user publishes a message to the channel, the agent receives it through the subscription callback.
+
+The following example demonstrates an agent subscribing to receive user input:
+
+
+```javascript
+const Ably = require('ably');
+
+const ably = new Ably.Realtime({ key: '{{API_KEY}}' });
+const channel = ably.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+await channel.subscribe('user-input', (message) => {
+ const { promptId, text } = message.data;
+ const userId = message.clientId;
+
+ console.log(`Received prompt from ${userId}: ${text}`);
+
+ // Process the prompt and generate a response
+ processAndRespond(channel, text, promptId);
+});
+```
+
+
+
+
+## Publish agent responses
+
+When the agent sends a response, it includes the `promptId` from the original input so users know which prompt the response relates to. This is especially important when users send multiple prompts in quick succession or when responses are streamed.
+
+Use the `extras.headers` field to include the `promptId` in agent responses:
+
+
+```javascript
+async function processAndRespond(channel, prompt, promptId) {
+ // Generate the response (e.g., call your AI model)
+ const response = await generateAIResponse(prompt);
+
+ // Publish the response with the promptId for correlation
+ await channel.publish({
+ name: 'agent-response',
+ data: response,
+ extras: {
+ headers: {
+ promptId: promptId
+ }
+ }
+ });
+}
+```
+
+
+The user's client can then match responses to their original prompts:
+
+
+```javascript
+const pendingPrompts = new Map();
+
+// Send a prompt and track it
+async function sendPrompt(text) {
+ const promptId = crypto.randomUUID();
+ pendingPrompts.set(promptId, { text });
+ await channel.publish('user-input', { promptId, text });
+ return promptId;
+}
+
+// Handle responses
+await channel.subscribe('agent-response', (message) => {
+ const promptId = message.extras?.headers?.promptId;
+
+ if (promptId && pendingPrompts.has(promptId)) {
+ const originalPrompt = pendingPrompts.get(promptId);
+ console.log(`Response for "${originalPrompt.text}": ${message.data}`);
+ pendingPrompts.delete(promptId);
+ }
+});
+```
+
+
+
+
+## Stream responses
+
+For longer AI responses, you'll typically want to stream tokens back to the user rather than waiting for the complete response. The `promptId` correlation allows users to associate streamed tokens with their original prompt.
+
+When streaming tokens using [message-per-response](/docs/ai-transport/token-streaming/message-per-response) or [message-per-token](/docs/ai-transport/token-streaming/message-per-token) patterns, include the `promptId` in the message extras:
+
+
+```javascript
+async function streamResponse(channel, prompt, promptId) {
+ // Create initial message for message-per-response pattern
+ const message = await channel.publish({
+ name: 'agent-response',
+ data: '',
+ extras: {
+ headers: {
+ promptId: promptId
+ }
+ }
+ });
+
+ // Stream tokens by appending to the message
+ for await (const token of generateTokens(prompt)) {
+ await channel.appendMessage({
+ serial: message.serial,
+ data: token,
+ extras: {
+ headers: {
+ promptId: promptId
+ }
+ }
+ });
+ }
+}
+```
+
+
+
+
+## Handle multiple concurrent prompts
+
+Users may send multiple prompts before receiving responses, especially during long-running AI operations. The correlation pattern ensures responses are matched to the correct prompts:
+
+
+```javascript
+// Agent handling multiple concurrent prompts
+const activeRequests = new Map();
+
+await channel.subscribe('user-input', async (message) => {
+ const { promptId, text } = message.data;
+ const userId = message.clientId;
+
+ // Track active request
+ activeRequests.set(promptId, {
+ userId,
+ text,
+ });
+
+ try {
+ await streamResponse(channel, text, promptId);
+ } finally {
+ activeRequests.delete(promptId);
+ }
+});
+```
+
diff --git a/src/pages/docs/ai-transport/messaging/chain-of-thought.mdx b/src/pages/docs/ai-transport/messaging/chain-of-thought.mdx
new file mode 100644
index 0000000000..15c40d0dc0
--- /dev/null
+++ b/src/pages/docs/ai-transport/messaging/chain-of-thought.mdx
@@ -0,0 +1,266 @@
+---
+title: "Chain of thought"
+meta_description: "Stream chain-of-thought reasoning from thinking models in AI applications"
+meta_keywords: "chain of thought, thinking models, extended thinking, reasoning transparency, reasoning streams, thought process, AI transparency, separate channels, model reasoning, tool calls, reasoning tokens"
+---
+
+Modern AI applications stream chain-of-thought reasoning from thinking models alongside their output. Rather than immediately generating output, thinking models work through problems step-by-step, evaluating different approaches and refining their reasoning before and during output generation. Exposing this reasoning provides transparency into how the model arrived at its output, enabling richer user experiences and deeper insights into model behavior.
+
+## What is chain-of-thought?
+
+Chain-of-thought is the model's internal reasoning process as it works through a problem. Modern thinking models output this reasoning as a stream of messages that show how they evaluate options, consider trade-offs, and plan their approach while generating output.
+
+A single response from the model may consist of multiple output messages interleaved with reasoning messages, which are all associated with the same model response.
+
+As an application developer, you decide what reasoning to surface and to whom. You may choose to expose all reasoning, filter or summarize it (for example, via a separate model call), or keep internal thinking entirely private.
+
+Surfacing chain-of-thought reasoning provides:
+
+- Trust and transparency: Users can see how the AI reached its conclusions, building confidence in the output
+- Better user experience: Displaying reasoning in realtime provides feedback that the model is making progress during longer operations
+- Enhanced steerability: Users can intervene and redirect the model based on its reasoning so far, guiding it toward better outcomes
+
+## Streaming patterns
+
+As an application developer, you decide how to surface chain-of-thought reasoning to end users. Ably's pub/sub model is flexible and can accommodate any messaging pattern you choose. Below are a few common patterns used in modern AI applications, each showing both agent-side publishing and client-side subscription. Choose the approach that fits your use case, or create your own variation.
+
+### Inline pattern
+
+In the inline pattern, agents publish reasoning messages to the same channel as model output messages.
+
+By publishing all content to a single channel, the inline pattern:
+
+- Simplifies channel management by consolidating all conversation content in one place
+- Maintains relative order of reasoning and model output messages as the model generates them
+- Supports retrieving reasoning and response messages together from history
+
+#### Publish
+
+Publish both reasoning and model output messages to a single channel.
+
+In the example below, the `responseId` is included in the message [extras](/docs/messages#properties) to allow subscribers to correlate all messages belonging to the same response. The message [`name`](/docs/messages#properties) allows the client distinguish between the different message types:
+
+
+```javascript
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+// Example: stream returns events like:
+// { type: 'reasoning', text: "Let's break down the problem: 27 * 12", responseId: 'resp_abc123' }
+// { type: 'reasoning', text: 'First, I can split this into 27 * 10 + 27 * 2', responseId: 'resp_abc123' }
+// { type: 'reasoning', text: 'That gives us 270 + 54 = 324', responseId: 'resp_abc123' }
+// { type: 'message', text: '27 * 12 = 324', responseId: 'resp_abc123' }
+
+for await (const event of stream) {
+ if (event.type === 'reasoning') {
+ // Publish reasoning messages
+ await channel.publish({
+ name: 'reasoning',
+ data: event.text,
+ extras: {
+ headers: {
+ responseId: event.responseId
+ }
+ }
+ });
+ } else if (event.type === 'message') {
+ // Publish model output messages
+ await channel.publish({
+ name: 'message',
+ data: event.text,
+ extras: {
+ headers: {
+ responseId: event.responseId
+ }
+ }
+ });
+ }
+}
+```
+
+
+
+
+
+
+#### Subscribe
+
+Subscribe to both reasoning and model output messages on the same channel.
+
+In the example below, the `responseId` from the message [`extras`](/docs/api/realtime-sdk/messages#extras) is used to group reasoning and model output messages belonging to the same response. The message [`name`](/docs/messages#properties) allows the client distinguish between the different message types:
+
+
+```javascript
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+// Track responses by ID, each containing reasoning messages and final response
+const responses = new Map();
+
+// Subscribe to all events on the channel
+await channel.subscribe((message) => {
+ const responseId = message.extras?.headers?.responseId;
+
+ if (!responseId) {
+ console.warn('Message missing responseId');
+ return;
+ }
+
+ // Initialize response object if needed
+ if (!responses.has(responseId)) {
+ responses.set(responseId, {
+ reasoning: [],
+ message: ''
+ });
+ }
+
+ const response = responses.get(responseId);
+
+ // Handle each message type
+ switch (message.name) {
+ case 'message':
+ response.message = message.data;
+ break;
+ case 'reasoning':
+ response.reasoning.push(message.data);
+ break;
+ }
+
+ // Display the reasoning and response for this turn
+ console.log(`Response ${responseId}:`, response);
+});
+```
+
+
+
+
+### Threading pattern
+
+In the threading pattern, agents publish reasoning messages to a separate channel from model output messages. The reasoning channel name is communicated to clients, allowing them to discover where to obtain reasoning content on demand.
+
+By separating reasoning into its own channel, the threading pattern:
+
+- Keeps the main channel clean and focused on final responses without reasoning output cluttering the conversation history
+- Reduces bandwidth usage by delivering reasoning messages only when users choose to view them
+- Works well for long reasoning threads, where not all the detail needs to be immediately surfaced to the user, but is helpful to see on demand
+
+#### Publish
+
+Publish model output messages to the main conversation channel and reasoning messages to a dedicated reasoning channel. The reasoning channel name includes the response ID, creating a unique reasoning channel per response.
+
+In the example below, the agent sends a `start` control message on the main channel at the beginning of each response, which includes the response ID in the message [`extras`](/docs/api/realtime-sdk/messages#extras). Clients can derive the reasoning channel name from the response ID, allowing them to discover and subscribe to the stream of reasoning messages on demand:
+
+
+
+
+```javascript
+const conversationChannel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+// Example: stream returns events like:
+// { type: 'start', responseId: 'resp_abc123' }
+// { type: 'reasoning', text: "Let's break down the problem: 27 * 12", responseId: 'resp_abc123' }
+// { type: 'reasoning', text: 'First, I can split this into 27 * 10 + 27 * 2', responseId: 'resp_abc123' }
+// { type: 'reasoning', text: 'That gives us 270 + 54 = 324', responseId: 'resp_abc123' }
+// { type: 'message', text: '27 * 12 = 324', responseId: 'resp_abc123' }
+
+for await (const event of stream) {
+ if (event.type === 'start') {
+ // Publish response start control message
+ await conversationChannel.publish({
+ name: 'start',
+ extras: {
+ headers: {
+ responseId: event.responseId
+ }
+ }
+ });
+ } else if (event.type === 'reasoning') {
+ // Publish reasoning to separate reasoning channel
+ const reasoningChannel = realtime.channels.get(`{{RANDOM_CHANNEL_NAME}}:${event.responseId}`);
+
+ await reasoningChannel.publish({
+ name: 'reasoning',
+ data: event.text
+ });
+ } else if (event.type === 'message') {
+ // Publish model output to main channel
+ await conversationChannel.publish({
+ name: 'message',
+ data: event.text,
+ extras: {
+ headers: {
+ responseId: event.responseId
+ }
+ }
+ });
+ }
+}
+```
+
+
+
+
+
+
+#### Subscribe
+
+Subscribe to the main conversation channel to receive control messages and model output. Subscribe to the reasoning channel on demand, for example in response to a click event.
+
+In the example below, `responseId` from the message [`extras`](/docs/api/realtime-sdk/messages#extras) is used to derive the reasoning channel name, allowing clients to subscribe to the reasoning channel on demand to retrieve the reasoning associated with a response:
+
+
+```javascript
+const conversationChannel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+// Track responses by ID
+const responses = new Map();
+
+// Subscribe to all messages on the main channel
+await conversationChannel.subscribe((message) => {
+ const responseId = message.extras?.headers?.responseId;
+
+ if (!responseId) {
+ console.warn('Message missing responseId');
+ return;
+ }
+
+ // Handle response start control message
+ if (message.name === 'start') {
+ responses.set(responseId, '');
+ }
+
+ // Handle model output message
+ if (message.name === 'message') {
+ responses.set(responseId, message.data);
+ }
+});
+
+// Subscribe to reasoning on demand (e.g., when user clicks to view reasoning)
+async function onClickViewReasoning(responseId) {
+ // Derive reasoning channel name from responseId and
+ // use rewind to retrieve historical reasoning
+ const reasoningChannel = realtime.channels.get(`{{RANDOM_CHANNEL_NAME}}:${responseId}`, {
+ params: { rewind: '2m' }
+ });
+
+ // Subscribe to reasoning messages
+ await reasoningChannel.subscribe((message) => {
+ console.log(`[Reasoning]: ${message.data}`);
+ });
+}
+```
+
+
+
diff --git a/src/pages/docs/ai-transport/messaging/citations.mdx b/src/pages/docs/ai-transport/messaging/citations.mdx
new file mode 100644
index 0000000000..53d473b0be
--- /dev/null
+++ b/src/pages/docs/ai-transport/messaging/citations.mdx
@@ -0,0 +1,263 @@
+---
+title: "Citations"
+meta_description: "Attach source citations to AI responses using message annotations"
+meta_keywords: "citations, references, source attribution, message annotations, AI transparency, source tracking, annotation summaries"
+---
+
+AI agents often draw information from external sources such as documents, web pages, or databases. Citations to those sources enable users to verify information, explore sources in detail, and understand where responses came from. Ably's [message annotations](/docs/messages/annotations) provide a model-agnostic, structured way to attach source citations to AI responses without modifying the response content. It enables clients to append information to existing messages on a channel.
+
+This pattern works when publishing complete responses as messages on a channel or when streaming responses using the [message-per-response](/docs/ai-transport/message-per-response) pattern.
+
+## Why citations matter
+
+Including citations on AI responses provides:
+
+- Transparency: Users can verify claims and understand the basis for AI responses. This builds trust and allows users to fact-check information independently.
+- Source exploration: Citations enable users to dive deeper into topics by accessing original sources. This is particularly valuable for research, learning, and decision-making workflows.
+- Attribution: Proper attribution respects content creators and helps users understand which sources informed the AI's response.
+- Audit trails: For enterprise applications, citations provide explicit traceability between LLM responses and the information sources that were consulted when generating them.
+
+## How it works
+
+Use [message annotations](/docs/messages/annotations) to attach source metadata to AI response messages without modifying the response content:
+
+1. The agent publishes an AI response as a single message, or builds it incrementally using [message appends](/docs/ai-transport/message-per-response).
+2. The agent publishes one or more annotations to attach citations to the response message, each referencing the response message [`serial`](/docs/messages#properties).
+3. Ably automatically aggregates annotations and generates summaries showing total counts and groupings (for example, by source domain name).
+4. Clients receive citation summaries automatically and can optionally subscribe to individual annotation events for detailed citation data as part of the realtime stream. Alternatively, clients can obtain annotations for a given message via the REST API.
+
+## Enable message annotations
+
+Message append functionality requires "Message annotations, updates, deletes and appends" to be enabled in a [channel rule](/docs/channels#rules) associated with the channel.
+
+
+
+To enable the channel rule:
+
+1. Go to the [Ably dashboard](https://www.ably.com/dashboard) and select your app.
+2. Navigate to the "Configuration" > "Rules" section from the left-hand navigation bar.
+3. Choose "Add new rule".
+4. Enter a channel name or namespace pattern (for example, `ai` for all channels starting with `ai:`).
+5. Select the "Message annotations, updates, deletes and appends" option from the list.
+6. Click "Create channel rule".
+
+The examples in this guide use the `ai:` namespace prefix, which assumes you have configured the rule for `ai`.
+
+
+
+## Citation data model
+
+Citations are implemented using [message annotations](/docs/messages/annotations). Each citation includes an annotation `type` that determines how citations are aggregated into summaries, and a `data` payload containing the citation details.
+
+### Annotation type
+
+[Annotation types](/docs/messages/annotations#annotation-types) determine how annotations are processed and aggregated into summaries. The type is a string of the format `namespace:summarization_method`:
+
+- `namespace` is a string that logically groups related annotations. For example, use `citations` for AI response citations.
+- `summarization_method` specifies how annotations are aggregated to produce summaries.
+
+Use the [`multiple.v1`](/docs/messages/annotations#multiple) summarization method for AI response citations. This is well suited for citations because:
+
+- AI responses often reference the same source multiple times, and `multiple.v1` counts each citation separately.
+- Citations can be grouped by source using the `name` field (for example, by domain name), so clients can display "3 citations from wikipedia.org, 2 from nasa.gov".
+
+The examples below use the annotation type `citations:multiple.v1`.
+
+### Annotation data
+
+The annotation `data` field can contain any structured data relevant to your citation use case. For example, a citation for a web search result might include:
+
+
+```json
+{
+ "url": "https://example.com/article",
+ "title": "Example Article Title",
+ "startOffset": 120,
+ "endOffset": 180,
+ "snippet": "Short excerpt from source"
+}
+```
+
+
+In this example:
+
+- `url` is the source URL.
+- `title` is the title of the web page.
+- `startOffset` is the character position in the response where this citation begins.
+- `endOffset` is the character position in the response where the citation ends.
+- `snippet` is a short excerpt from the source content for preview displays.
+
+Including character offsets in annotation data allow UIs to attach inline citation markers to specific portions of the response text.
+
+
+
+## Publish citations
+
+Agents create citations by publishing [message annotations](/docs/messages/annotations) that reference the [`serial`](/docs/messages#properties) of the response message:
+
+
+```javascript
+const channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}');
+
+// Publish the AI response message
+const response = 'The James Webb Space Telescope launched in December 2021 and its first images were released in July 2022.';
+const { serials: [msgSerial] } = await channel.publish('response', response);
+
+// Add citations by annotating the response message
+await channel.annotations.publish(msgSerial, {
+ type: 'citations:multiple.v1',
+ name: 'science.nasa.gov',
+ data: {
+ url: 'https://science.nasa.gov/mission/webb/',
+ title: 'James Webb Space Telescope - NASA Science',
+ startOffset: 43,
+ endOffset: 56,
+ snippet: 'Webb launched on Dec. 25th 2021'
+ }
+});
+await channel.annotations.publish(msgSerial, {
+ type: 'citations:multiple.v1',
+ name: 'en.wikipedia.org',
+ data: {
+ url: 'https://en.wikipedia.org/wiki/James_Webb_Space_Telescope',
+ title: 'James Webb Space Telescope - Wikipedia',
+ startOffset: 95,
+ endOffset: 104,
+ snippet: 'The telescope\'s first image was released to the public on 11 July 2022.'
+ }
+});
+```
+
+
+
+
+
+
+
+
+## Subscribe to summaries
+
+
+Clients can display a summary of the citations attached to a response by using [annotation summaries](/docs/messages/annotations#annotation-summaries). Clients receive realtime updates to annotation summaries automatically when subscribing to a channel, which are [delivered as messages](/docs/messages/annotations#subscribe) with an `action` of `message.summary`. When using [`multiple.v1`](/docs/messages/annotations#multiple) summarization, counts are grouped by the annotation `name`.
+
+
+
+In the example below, the `name` is set to the domain name of the citation source, so summaries show counts per domain:
+
+
+```javascript
+const channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}');
+
+await channel.subscribe((message) => {
+ if (message.action === 'message.summary') {
+ const citations = message.annotations.summary['citations:multiple.v1'];
+ if (citations) {
+ console.log('Citation summary:', citations);
+ }
+ }
+});
+```
+
+
+The `multiple.v1` summary groups counts by the annotation `name`, with totals and per-client breakdowns for each group:
+
+
+```json
+{
+ "citations:multiple.v1": {
+ "science.nasa.gov": {
+ "total": 1,
+ "clientIds": {
+ "research-agent": 1
+ },
+ "totalUnidentified": 0,
+ "totalClientIds": 1,
+ "clipped": false
+ },
+ "en.wikipedia.org": {
+ "total": 1,
+ "clientIds": {
+ "research-agent": 1
+ },
+ "totalUnidentified": 0,
+ "totalClientIds": 1,
+ "clipped": false
+ }
+ }
+}
+```
+
+
+When agents publish citations with a [`clientId`](/docs/auth/identified-clients), summaries include a per-client count showing how many citations each agent contributed. Citations published by [unidentified](/docs/auth/identified-clients#unidentified) clients are counted in the `totalUnidentified` field.
+
+
+
+## Subscribe to individual citations
+
+To access the full citation data, subscribe to [individual annotation events](/docs/messages/annotations#individual-annotations):
+
+
+```javascript
+const channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}', {
+ modes: ['ANNOTATION_SUBSCRIBE']
+});
+
+await channel.annotations.subscribe((annotation) => {
+ if (annotation.action === 'annotation.create' &&
+ annotation.type === 'citations:multiple.v1') {
+ const { url, title } = annotation.data;
+ console.log(`Citation: ${title} (${url})`);
+ // Output: Citation: James Webb Space Telescope - Wikipedia (https://en.wikipedia.org/wiki/James_Webb_Space_Telescope)
+ }
+});
+```
+
+
+Each annotation event includes the `messageSerial` of the response message it is attached to, the `name` used for grouping in summaries, and the full citation `data` payload. This data can be used to render clickable source links or attach inline citation markers to specific portions of the response text:
+
+
+```json
+{
+ "action": "annotation.create",
+ "clientId": "research-agent",
+ "type": "citations:multiple.v1",
+ "messageSerial": "01767638186693-000@108SP4XcgBxfMO07491612:000",
+ "name": "en.wikipedia.org",
+ "data": {
+ "url": "https://en.wikipedia.org/wiki/James_Webb_Space_Telescope",
+ "title": "James Webb Space Telescope - Wikipedia",
+ "startOffset": 95,
+ "endOffset": 104,
+ "snippet": "The telescope's first image was released to the public on 11 July 2022."
+ }
+}
+```
+
+
+
+
+## Retrieve citations on demand
+
+Annotations can also be retrieved via the [REST API](/docs/api/rest-api#annotations-list) without maintaining a realtime subscription.
+
+
diff --git a/src/pages/docs/ai-transport/messaging/human-in-the-loop.mdx b/src/pages/docs/ai-transport/messaging/human-in-the-loop.mdx
new file mode 100644
index 0000000000..3b9c075259
--- /dev/null
+++ b/src/pages/docs/ai-transport/messaging/human-in-the-loop.mdx
@@ -0,0 +1,205 @@
+---
+title: "Human in the loop"
+meta_description: "Implement human-in-the-loop workflows for AI agents using Ably capabilities and claims to ensure authorized users approve sensitive tool calls."
+meta_keywords: "human in the loop, HITL, AI agent authorization, tool call approval, JWT claims, capabilities, admin approval, agentic workflows, AI safety, human oversight"
+---
+
+Human-in-the-loop (HITL) enables human oversight of AI agent actions. When an agent needs to perform sensitive operations, such as modifying data, performing sensitive actions, or accessing restricted resources, the action is paused and routed to an authorized human for approval before execution.
+
+This pattern ensures humans remain in control of high-stakes AI operations, providing safety, compliance, and trust in agentic workflows.
+
+## Why human-in-the-loop matters
+
+AI agents are increasingly capable of taking autonomous actions, but certain operations require human judgment:
+
+- Safety: Prevent unintended consequences from AI decisions.
+- Compliance: Meet regulatory requirements for human oversight in sensitive domains.
+- Trust: Build user confidence by keeping humans in control of critical actions.
+- Accountability: Create clear audit trails of who approved what actions.
+- Clarification: Allow the agent to request more information or guidance from users before proceeding.
+
+HITL puts a human approval step in front of agent actions that carry risk or uncertainty.
+
+## How it works
+
+Human-in-the-loop authorization follows a request-approval pattern over Ably channels:
+
+1. The AI agent determines a tool call requires human approval.
+2. The agent publishes an authorization request to the channel.
+3. An authorized user receives and reviews the request.
+4. The human approves or rejects the request.
+5. The agent receives the decision, verifies the responder's identity or role and proceeds accordingly.
+
+## Request human approval
+
+When an agent identifies an action requiring human oversight, it publishes a request to the channel. The request should include sufficient context for the approver to make an informed decision. The `requestId` enables correlation between requests and responses when handling multiple concurrent approval flows.
+
+
+```javascript
+const channel = ably.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+async function requestHumanApproval(toolCall) {
+ const requestId = crypto.randomUUID();
+
+ await channel.publish('approval-request', {
+ requestId: requestId,
+ action: toolCall.name,
+ parameters: toolCall.parameters
+ });
+
+ return requestId;
+}
+```
+
+
+
+
+## Review and decide
+
+Authorized humans subscribe to approval requests on the conversation channel and publish their decisions. The `requestId` correlates the response with the original request.
+
+Use [identified clients](/docs/ai-transport/sessions-identity/identifying-users-and-agents#user-identity) or [user claims](/docs/ai-transport/sessions-identity/identifying-users-and-agents#user-claims) to establish a verified identity or role for the approver. For example, when a user [authenticates with Ably](/docs/ai-transport/sessions-identity/identifying-users-and-agents#authenticating), embed their identity and role in the JWT:
+
+
+```javascript
+const claims = {
+ 'x-ably-clientId': 'user-123',
+ 'ably.channel.*': 'user'
+};
+```
+
+
+The `clientId` and user claims are automatically attached to every message the user publishes and cannot be forged, so agents can trust this identity and role information.
+
+
+
+
+```javascript
+const channel = ably.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+await channel.subscribe('approval-request', (message) => {
+ const request = message.data;
+ // Display request for human review
+ displayApprovalUI(request);
+});
+
+async function approve(requestId) {
+ await channel.publish('approval-response', {
+ requestId: requestId,
+ decision: 'approved'
+ });
+}
+
+async function reject(requestId) {
+ await channel.publish('approval-response', {
+ requestId: requestId,
+ decision: 'rejected'
+ });
+}
+```
+
+
+
+
+## Process the decision
+
+The agent listens for human decisions and acts accordingly. When a response arrives, the agent retrieves the pending request using the `requestId`, verifies that the user is permitted to approve that specific action, and either executes the action or handles the rejection.
+
+
+
+### Verify by user identity
+
+Use the `clientId` to identify the approver and look up their permissions in your database or user management system. This approach is useful when permissions are managed externally or change frequently.
+
+
+
+
+```javascript
+const pendingApprovals = new Map();
+
+await channel.subscribe('approval-response', async (message) => {
+ const response = message.data;
+ const pending = pendingApprovals.get(response.requestId);
+
+ if (!pending) return;
+
+ // The clientId is verified by Ably - this is the trusted approver identity
+ const approverId = message.clientId;
+
+ // Look up user-specific permissions from your database
+ const userPermissions = await getUserPermissions(approverId);
+
+ if (!userPermissions.canApprove(pending.toolCall.name)) {
+ console.log(`User ${approverId} not authorized to approve ${pending.toolCall.name}`);
+ return;
+ }
+
+ if (response.decision === 'approved') {
+ const result = await executeToolCall(pending.toolCall);
+ console.log(`Action approved by ${approverId}`);
+ } else {
+ console.log(`Action rejected by ${approverId}`);
+ }
+
+ pendingApprovals.delete(response.requestId);
+});
+```
+
+
+### Verify by role
+
+Use [user claims](/docs/auth/capabilities#custom-restrictions-on-channels-) to embed roles directly in the JWT for role-based access control (RBAC). This approach is useful when permissions are role-based rather than user-specific, allowing you to make authorization decisions based on the user's role without looking up individual user permissions.
+
+
+
+Different actions may require different authorization levels - for example, a user might approve low-value purchases, a manager might approve purchases up to a certain limit, while an admin can approve any purchase amount. When an approval arrives, compare the approver's role against the minimum required role for that action type:
+
+
+```javascript
+const roleHierarchy = ['user', 'manager', 'admin'];
+
+function canApprove(approverRole, requiredRole) {
+ const approverLevel = roleHierarchy.indexOf(approverRole);
+ const requiredLevel = roleHierarchy.indexOf(requiredRole);
+
+ return approverLevel >= requiredLevel;
+}
+
+// When processing approval response
+await channel.subscribe('approval-response', async (message) => {
+ const response = message.data;
+ const pending = pendingApprovals.get(response.requestId);
+ const policy = approvalPolicies[pending.toolCall.name];
+
+ // Get the trusted role from the JWT claim
+ const approverRole = message.extras?.userClaim;
+
+ // Verify the approver's role meets the minimum required role for this action
+ if (!canApprove(approverRole, policy.minRole)) {
+ console.log(`Approver role '${approverRole}' insufficient for required '${policy.minRole}'`);
+ return;
+ }
+
+ if (response.decision === 'approved') {
+ const result = await executeToolCall(pending.toolCall);
+ console.log(`Action approved by role ${approverRole}`);
+ } else {
+ console.log(`Action rejected by role ${approverRole}`);
+ }
+
+ pendingApprovals.delete(response.requestId);
+});
+```
+
diff --git a/src/pages/docs/ai-transport/messaging/tool-calls.mdx b/src/pages/docs/ai-transport/messaging/tool-calls.mdx
new file mode 100644
index 0000000000..15de573ff2
--- /dev/null
+++ b/src/pages/docs/ai-transport/messaging/tool-calls.mdx
@@ -0,0 +1,278 @@
+---
+title: "Tool calls"
+meta_description: "Stream tool call execution visibility to users, enabling transparent AI interactions and generative UI experiences."
+meta_keywords: "tool calls, function calling, generative UI, AI transparency, tool execution, streaming JSON, realtime feedback"
+---
+
+Modern AI models can invoke tools (also called functions) to perform specific tasks like retrieving data, performing calculations, or triggering actions. Streaming tool call information to users provides visibility into what the AI is doing, creates opportunities for rich generative UI experiences, and builds trust through transparency.
+
+## What are tool calls?
+
+Tool calls occur when an AI model decides to invoke a specific function or tool to accomplish a task. Rather than only returning text, the model can request to execute tools you've defined, such as fetching weather data, searching a database, or performing calculations.
+
+A tool call consists of:
+
+- Tool name: The identifier of the tool being invoked
+- Tool input: Parameters passed to the tool, often structured as JSON
+- Tool output: The result returned after execution
+
+As an application developer, you decide how to surface tool calls to users. You may choose to display all tool calls, selectively surface specific tools or inputs/outputs, or keep tool calls entirely private.
+
+Surfacing tool calls supports:
+
+- Trust and transparency: Users see what actions the AI is taking, building confidence in the agent
+- Human-in-the-loop workflows: Expose tool calls [resolved by humans](/docs/ai-transport/messaging/human-in-the-loop) where users can review and approve tool execution before it happens
+- Generative UI: Build dynamic, contextual UI components based on the structured tool data
+
+## Publish tool calls
+
+Publish tool call and model output messages to the channel.
+
+In the example below, the `responseId` is included in the message [extras](/docs/messages#properties) to allow subscribers to correlate all messages belonging to the same response. The message [`name`](/docs/messages#properties) allows the client to distinguish between the different message types:
+
+
+```javascript
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+// Example: stream returns events like:
+// { type: 'tool_call', name: 'get_weather', args: '{"location":"San Francisco"}', toolCallId: 'tool_123', responseId: 'resp_abc123' }
+// { type: 'tool_result', name: 'get_weather', result: '{"temp":72,"conditions":"sunny"}', toolCallId: 'tool_123', responseId: 'resp_abc123' }
+// { type: 'message', text: 'The weather in San Francisco is 72°F and sunny.', responseId: 'resp_abc123' }
+
+for await (const event of stream) {
+ if (event.type === 'tool_call') {
+ // Publish tool call arguments
+ await channel.publish({
+ name: 'tool_call',
+ data: {
+ name: event.name,
+ args: event.args
+ },
+ extras: {
+ headers: {
+ responseId: event.responseId,
+ toolCallId: event.toolCallId
+ }
+ }
+ });
+ } else if (event.type === 'tool_result') {
+ // Publish tool call results
+ await channel.publish({
+ name: 'tool_result',
+ data: {
+ name: event.name,
+ result: event.result
+ },
+ extras: {
+ headers: {
+ responseId: event.responseId,
+ toolCallId: event.toolCallId
+ }
+ }
+ });
+ } else if (event.type === 'message') {
+ // Publish model output messages
+ await channel.publish({
+ name: 'message',
+ data: event.text,
+ extras: {
+ headers: {
+ responseId: event.responseId
+ }
+ }
+ });
+ }
+}
+```
+
+
+
+
+
+
+
+
+## Subscribe to tool calls
+
+Subscribe to tool call and model output messages on the channel.
+
+In the example below, the `responseId` from the message [`extras`](/docs/api/realtime-sdk/messages#extras) is used to group tool calls and model output messages belonging to the same response. The message [`name`](/docs/messages#properties) allows the client to distinguish between the different message types:
+
+
+```javascript
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+// Track responses by ID, each containing tool calls and final response
+const responses = new Map();
+
+// Subscribe to all events on the channel
+await channel.subscribe((message) => {
+ const responseId = message.extras?.headers?.responseId;
+
+ if (!responseId) {
+ console.warn('Message missing responseId');
+ return;
+ }
+
+ // Initialize response object if needed
+ if (!responses.has(responseId)) {
+ responses.set(responseId, {
+ toolCalls: new Map(),
+ message: ''
+ });
+ }
+
+ const response = responses.get(responseId);
+
+ // Handle each message type
+ switch (message.name) {
+ case 'message':
+ response.message = message.data;
+ break;
+ case 'tool_call':
+ const toolCallId = message.extras?.headers?.toolCallId;
+ response.toolCalls.set(toolCallId, {
+ name: message.data.name,
+ args: message.data.args
+ });
+ break;
+ case 'tool_result':
+ const resultToolCallId = message.extras?.headers?.toolCallId;
+ const toolCall = response.toolCalls.get(resultToolCallId);
+ if (toolCall) {
+ toolCall.result = message.data.result;
+ }
+ break;
+ }
+
+ // Display the tool calls and response for this turn
+ console.log(`Response ${responseId}:`, response);
+});
+```
+
+
+
+
+## Generative UI
+
+Tool calls provide structured data that can form the basis of generative UI - dynamically creating UI components based on the tool being invoked, its parameters, and the results returned. Rather than just displaying raw tool call information, you can render rich, contextual components that provide a better user experience.
+
+For example, when a weather tool is invoked, instead of showing raw JSON like `{ location: 'San Francisco', temp: 72, conditions: 'sunny' }`, you can render a weather card component with icons, formatted temperature, and visual indicators:
+
+
+```javascript
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+await channel.subscribe((message) => {
+ // Render component when tool is invoked
+ if (message.name === 'tool_call' && message.data.name === 'get_weather') {
+ const args = JSON.parse(message.data.args);
+ renderWeatherCard({ location: args.location, loading: true });
+ }
+
+ // Update component with results
+ if (message.name === 'tool_result' && message.data.name === 'get_weather') {
+ const result = JSON.parse(message.data.result);
+ renderWeatherCard(result);
+ }
+});
+```
+
+
+
+
+## Client-side tools
+
+Some tools need to be executed directly on the client device rather than on the server, allowing agents to dynamically access information available on the end user's device as needed. These include tools that access device capabilities such as GPS location, camera, SMS, local files, or other native functionality.
+
+Client-side tool calls follow a request-response pattern over Ably channels:
+
+1. The agent publishes a tool call request to the channel.
+2. The client receives and executes the tool using device APIs.
+3. The client publishes the result back to the channel.
+4. The agent receives the result and continues processing.
+
+
+
+The client subscribes to tool call requests, executes the tool using device APIs, and publishes the result back to the channel. The `toolCallId` enables correlation between tool call requests and results:
+
+
+```javascript
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+await channel.subscribe('tool_call', async (message) => {
+ const { name, args } = message.data;
+ const { responseId, toolCallId } = message.extras?.headers || {};
+
+ if (name === 'get_location') {
+ const result = await getGeolocationPosition();
+ await channel.publish({
+ name: 'tool_result',
+ data: {
+ name: name,
+ result: {
+ lat: result.coords.latitude,
+ lng: result.coords.longitude
+ }
+ },
+ extras: {
+ headers: {
+ responseId: responseId,
+ toolCallId: toolCallId
+ }
+ }
+ });
+ }
+});
+```
+
+
+
+
+
+
+The agent subscribes to tool results to continue processing. The `toolCallId` correlates the result back to the original request:
+
+
+```javascript
+const pendingToolCalls = new Map();
+
+await channel.subscribe('tool_result', (message) => {
+ const { toolCallId, result } = message.data;
+ const pending = pendingToolCalls.get(toolCallId);
+
+ if (!pending) return;
+
+ // Pass result back to the AI model to continue the conversation
+ processResult(pending.responseId, toolCallId, result);
+
+ pendingToolCalls.delete(toolCallId);
+});
+```
+
+
+## Human-in-the-loop workflows
+
+Tool calls resolved by humans are one approach to implementing human-in-the-loop workflows. When an agent encounters a tool call that needs human resolution, it publishes the tool call to the channel and waits for the human to publish the result back over the channel.
+
+For example, a tool that modifies data, performs financial transactions, or accesses sensitive resources might require explicit user approval before execution. The tool call information is surfaced to the user, who can then approve or reject the action.
+
+
diff --git a/src/pages/docs/ai-transport/sessions-identity/identifying-users-and-agents.mdx b/src/pages/docs/ai-transport/sessions-identity/identifying-users-and-agents.mdx
new file mode 100644
index 0000000000..f762d4ae87
--- /dev/null
+++ b/src/pages/docs/ai-transport/sessions-identity/identifying-users-and-agents.mdx
@@ -0,0 +1,419 @@
+---
+title: "Identifying users and agents"
+meta_description: "Establish trusted identity and roles in decoupled AI sessions"
+meta_keywords: "user authentication, agent identity, JWT authentication, token authentication, verified identity, capabilities, authorization, user claims, RBAC, role-based access control, API key authentication, message attribution"
+---
+
+Secure AI applications require agents to trust who sent each message and understand what that sender is authorized to do. Ably's identity system uses token-based authentication to provide cryptographically-verified identities with custom attributes that you can access throughout your applications.
+
+## Why identity matters
+
+In decoupled architectures, identity serves several critical purposes:
+
+- Prevent spoofing: Without verified identity, malicious users could impersonate others by claiming to be someone else. Ably supports cryptographically binding each client's identity to their credentials, making spoofing impossible.
+- Message attribution: Agents need to know whether messages come from users or other agents. This is essential for conversation flows in which agent responses should be securely distinguished from user prompts.
+- Personalized behavior: Different users may have different privileges or attributes. A premium user might get access to more capable models, while a free user gets basic functionality. Ably allows your trusted authentication server to embed this information in the client's credentials, allowing this information to be securely passed to agents.
+- Authorization decisions: Some operations should only be performed for specific users. For example, human-in-the-loop (HITL) tool calls that access sensitive data might require admin privileges. Ably allows agents to verify the privilege level and role of the user resolving the tool call.
+
+## Authenticating users
+
+Use [token authentication](/docs/auth/token) to authenticate users securely. Your authentication server generates a token that is signed with the secret part of your Ably API key. Clients use this token to connect to Ably, and the token signature ensures it cannot be tampered with.
+
+The following examples use [JWT authentication](/docs/auth/token#jwt) for its simplicity and standard tooling support. For other approaches, see [token authentication](/docs/auth/token).
+
+Create a server endpoint that generates signed JWTs after verifying user authentication:
+
+
+```javascript
+// Server code
+import express from "express";
+import jwt from "jsonwebtoken";
+
+const app = express();
+
+// Mock authentication middleware.
+// This should be replaced with your actual authentication logic.
+function authenticateUser(req, res, next) {
+ // Assign a mock user ID for demonstration
+ req.session = { userId: "user123" };
+ next();
+}
+
+// Return the claims payload to embed in the signed JWT.
+function getJWTClaims(userId) {
+ // Returns an empty payload, so the token
+ // inherits the capabilities of the signing key.
+ return {};
+}
+
+// Define an auth endpoint used by the client to obtain a signed JWT
+// which it can use to authenticate with the Ably service.
+app.get("/api/auth/token", authenticateUser, (req, res) => {
+ const [keyName, keySecret] = "{{API_KEY}}".split(":");
+
+ // Sign a JWT using the secret part of the Ably API key.
+ const token = jwt.sign(getJWTClaims(req.session.userId), keySecret, {
+ algorithm: "HS256",
+ keyid: keyName,
+ expiresIn: "1h",
+ });
+
+ res.type("application/jwt").send(token);
+});
+
+app.listen(3001);
+```
+
+
+
+
+The JWT is signed with the secret part of your Ably API key using [HMAC-SHA-256](https://datatracker.ietf.org/doc/html/rfc4868). This example does not embed any claims in the JWT payload, so by default the token inherits the capabilities of the Ably API key used to sign the token.
+
+Configure your client to obtain a signed JWT from your server endpoint using an [`authCallback`](/docs/auth/token#auth-callback). The client obtains a signed JWT from the callback and uses it to authenticate requests to Ably. The client automatically makes a request for a new token before it expires.
+
+
+
+
+```javascript
+// Client code
+import * as Ably from "ably";
+
+const ably = new Ably.Realtime({
+ authCallback: async (tokenParams, callback) => {
+ try {
+ const response = await fetch("/api/auth/token");
+ const token = await response.text();
+ callback(null, token);
+ } catch (error) {
+ callback(error, null);
+ }
+ }
+});
+
+ably.connection.on("connected", () => {
+ console.log("Connected to Ably");
+});
+```
+
+
+## Authenticating agents
+
+Agents typically run on servers in trusted environments where API keys can be securely stored. Use [API key authentication](/docs/auth#basic-authentication) to authenticate agents directly with Ably.
+
+
+```javascript
+// Agent code
+import * as Ably from "ably";
+
+const ably = new Ably.Realtime({
+ key: "{{API_KEY}}"
+});
+
+ably.connection.on("connected", () => {
+ console.log("Connected to Ably");
+});
+```
+
+
+
+
+
+
+## Specifying capabilities
+
+Use [capabilities](/docs/auth/capabilities) to specify which operations clients can perform on which channels. This applies to both users and agents, allowing you to enforce fine-grained permissions.
+
+### User capabilities
+
+Add the [`x-ably-capability`](/docs/api/realtime-sdk/authentication#ably-jwt) claim to your JWT to specify the allowed capabilities of a client. This allows you to enforce fine-grained permissions, such as restricting some users to only subscribe to messages while allowing others to publish.
+
+Update your `getJWTClaims` function to specify the allowed capabilities for the authenticated user:
+
+
+```javascript
+// Server code
+
+// Return the claims payload to embed in the signed JWT.
+// Includes the `x-ably-capabilities` claim, which controls
+// which operations the user can perform on which channels.
+function getJWTClaims(userId) {
+ const orgId = "acme"; // Mock organization ID for demonstration
+ const capabilities = {
+ // The user can publish and subscribe to channels within the organization,
+ // that is, any channel matching `org:acme:*`.
+ [`org:${orgId}:*`]: ["publish", "subscribe"],
+ // The user can only subscribe to the `announcements` channel.
+ announcements: ["subscribe"],
+ };
+ return {
+ "x-ably-capability": JSON.stringify(capabilities),
+ };
+}
+```
+
+
+When a client authenticates with this token, Ably enforces these capabilities server-side. Any attempt to perform unauthorized operations will be rejected. For example, a client with the capabilities above can publish to channels prefixed with `org:acme:`, but an attempt to publish to a channel prefixed with `org:foobar:` will fail with error code [`40160`](/docs/platform/errors/codes#40160):
+
+
+```javascript
+// Client code
+const acmeChannel = ably.channels.get("org:acme:{{RANDOM_CHANNEL_NAME}}");
+await acmeChannel.publish("prompt", "What is the weather like today?"); // succeeds
+
+const foobarChannel = ably.channels.get("org:foobar:{{RANDOM_CHANNEL_NAME}}");
+await foobarChannel.publish("prompt", "What is the weather like today?"); // fails
+
+const announcementsChannel = ably.channels.get("announcements");
+await announcementsChannel.publish("prompt", "What is the weather like today?"); // fails
+await announcementsChannel.subscribe((msg) => console.log(msg)); // succeeds
+```
+
+
+
+
+### Agent capabilities
+
+When using API key authentication, provision API keys through the [Ably dashboard](https://ably.com/dashboard) or [Control API](/docs/account/control-api) with only the capabilities required by the agent.
+
+The following example uses the Control API to create an API key with specific capabilities for a weather agent:
+
+
+
+
+```shell
+curl --location --request POST 'https://control.ably.net/v1/apps/{{APP_ID}}/keys' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
+--data-raw '{
+ "name": "weather-agent-key",
+ "capability": {
+ "org:acme:weather:*": ["publish", "subscribe"]
+ }
+}'
+```
+
+
+This creates an API key that can only publish and subscribe on channels matching `org:acme:weather:*`. The agent can then use this key to authenticate:
+
+
+```javascript
+// Agent code
+const weatherChannel = ably.channels.get("org:acme:weather:{{RANDOM_CHANNEL_NAME}}");
+await weatherChannel.subscribe((msg) => console.log(msg)); // succeeds
+await weatherChannel.publish("update", "It's raining in London"); // succeeds
+
+const otherChannel = ably.channels.get("org:acme:other:{{RANDOM_CHANNEL_NAME}}");
+await otherChannel.subscribe((msg) => console.log(msg)); // fails
+await otherChannel.publish("update", "It's raining in London"); // fails
+```
+
+
+
+
+## Establishing verified identity
+
+Use the [`clientId`](/docs/messages#properties) to identify the user or agent that published a message. The method for setting `clientId` depends on your authentication approach:
+
+- When using [basic authentication](/docs/auth/identified-clients#basic), specify the `clientId` directly in the client options when instantiating the client instance.
+- When using [token authentication](/docs/auth/identified-clients#token), specify an explicit `clientId` when issuing the token.
+
+### User identity
+
+Users typically authenticate using [token authentication](/docs/auth/identified-clients#token). Add the [`x-ably-clientId`](/docs/api/realtime-sdk/authentication#ably-jwt) claim to your JWT to establish a verified identity for each user client. This identity appears as the [`clientId`](/docs/messages#properties) in all messages the user publishes, and subscribers can trust this identity because only your server can issue JWTs with specific `clientId` values.
+
+As with all clients, the method for setting `clientId` depends on your [authentication approach](#identity).
+
+Update your `getJWTClaims` function to specify a `clientId` for the user:
+
+
+```javascript
+// Return the claims payload to embed in the signed JWT.
+function getJWTClaims(userId) {
+ // Returns a payload with the `x-ably-clientId` claim, which ensures
+ // that the user's ID appears as the `clientId` on all messages
+ // published by the client using this token.
+ return { "x-ably-clientId": userId };
+}
+```
+
+
+When a client authenticates using this token, Ably's servers automatically attach the `clientId` specified in the token to every message the user publishes:
+
+
+```javascript
+// Client code
+const channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Publish a message - the clientId is automatically attached
+await channel.publish("prompt", "What is the weather like today?");
+```
+
+
+Agents can then access this verified identity to identify the sender:
+
+
+```javascript
+// Agent code
+const channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Subscribe to messages from clients
+await channel.subscribe("prompt", (message) => {
+ // Access the verified clientId from the message
+ const userId = message.clientId;
+ const prompt = message.data;
+
+ console.log(`Received message from user: ${userId}`);
+ console.log(`Prompt:`, prompt);
+});
+```
+
+
+The `clientId` in the message can be trusted, so agents can use this identity to make decisions about what actions the user can take. For example, agents can check user permissions before executing tool calls, route messages to appropriate AI models based on subscription tiers, or maintain per-user conversation history and context.
+
+### Agent identity
+
+Agent code typically runs in a trusted environment, so you can use [basic authentication](/docs/auth/identified-clients#basic) and directly specify the `clientId` when instantiating the agent client. This identity appears as the [`clientId`](/docs/messages#properties) in all messages the agent publishes, allowing subscribers to identify the agent which published a message.
+
+
+```javascript
+// Agent code
+import * as Ably from "ably";
+
+const ably = new Ably.Realtime({
+ key: "{{API_KEY}}",
+ // Specify an identity for this agent
+ clientId: "weather-agent"
+});
+```
+
+
+When subscribers receive messages, they can use the `clientId` to determine which agent published the message:
+
+
+```javascript
+// Client code
+const channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+await channel.subscribe((message) => {
+ if (message.clientId === "weather-agent") {
+ console.log("Weather agent response:", message.data);
+ }
+});
+```
+
+
+
+
+## Adding roles and attributes
+
+Embed custom roles and attributes in messages to enable role-based access control (RBAC) and convey additional context about users and agents. This enables agents to make authorization decisions without additional database lookups.
+
+### User claims
+
+Use [authenticated claims for users](/docs/auth/capabilities#custom-restrictions-on-channels-) to embed custom claims in JWTs that represent user roles or attributes.
+
+Add claims with names matching the `ably.channel.*` pattern to your JWT to specify user claims for specific channels. Claims can be scoped to individual channels or to [namespaces](/docs/channels#namespaces) of channels. The most specific user claim matching the channel is automatically included under `extras.userClaim` in all messages the client publishes.
+
+Update your `getJWTClaims` function to specify some user claims:
+
+
+```javascript
+// Return the claims payload to embed in the signed JWT.
+function getJWTClaims(userId) {
+ // Returns a payload with `ably.channel.*` claims, which ensures that
+ // the most specific claim appears as the `message.extras.userClaim`
+ // on all messages published by the client using this token.
+ return {
+ // The user is an editor on all acme channels.
+ "ably.channel.org:acme:*": "editor",
+ // The user is a guest on all other channels.
+ "ably.channel.*": "guest",
+ };
+}
+```
+
+
+When a client authenticates with a JWT containing `ably.channel.*` claims, Ably automatically includes the most specific matching claim value in the `message.extras.userClaim` field on messages published by the client:
+
+
+```javascript
+// Agent code
+const channel = ably.channels.get("org:acme:{{RANDOM_CHANNEL_NAME}}");
+
+// Subscribe to user prompts
+await channel.subscribe("prompt", async (message) => {
+ // Access the user's role from the user claim in message extras
+ const role = message.extras?.userClaim;
+
+ console.log(`Message from user with role: ${role}`);
+});
+```
+
+
+The `message.extras.userClaim` in the message can be trusted, so agents can rely on this information to make decisions about what actions the user can take. For example, an agent could allow users with an "editor" role to execute tool calls that modify documents, while restricting users with a "guest" role to read-only operations.
+
+### Agent metadata
+
+Use [`message.extras.headers`](/docs/api/realtime-sdk/types#extras) to include custom metadata in agent messages, such as agent roles or attributes.
+
+Agents can directly specify metadata in `message.extras.headers`. Since agents run as trusted code in server environments, this metadata can be trusted by subscribers. This is useful for communicating agent characteristics, such as which model the agent uses, the agent's role in a multi-agent system, or version information.
+
+
+
+
+```javascript
+// Agent code
+import * as Ably from "ably";
+
+const ably = new Ably.Realtime({
+ key: "{{API_KEY}}",
+ clientId: "weather-agent"
+});
+
+const channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+await channel.publish({
+ name: "update",
+ data: "It's raining in London",
+ extras: {
+ headers: {
+ model: "gpt-4"
+ }
+ }
+});
+```
+
+
+Clients and other agents can access this metadata when messages are received:
+
+
+```javascript
+// Client code
+const channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+await channel.subscribe((message) => {
+ if (message.clientId === "weather-agent") {
+ const model = message.extras?.headers?.model;
+ console.log(`Response from weather agent using ${model}:`, message.data);
+ }
+});
+```
+
diff --git a/src/pages/docs/ai-transport/sessions-identity/index.mdx b/src/pages/docs/ai-transport/sessions-identity/index.mdx
new file mode 100644
index 0000000000..828fdd6538
--- /dev/null
+++ b/src/pages/docs/ai-transport/sessions-identity/index.mdx
@@ -0,0 +1,63 @@
+---
+title: "Sessions & identity overview"
+meta_description: "Manage session lifecycle and identity in decoupled AI architectures"
+meta_keywords: "AI sessions, session management, channel-oriented sessions, connection-oriented sessions, session persistence, session lifecycle, identity management, decoupled architecture, session resumption, multi-device, multi-user"
+---
+
+Ably AI Transport provides robust session management and identity capabilities designed for modern AI applications. Sessions persist beyond individual connections, enabling agents and clients to connect independently through shared channels. Built-in token-based authentication provides verified user identity and fine-grained authorization for channel operations.
+
+## What is a session?
+
+A session is an interaction between a user (or multiple users) and an AI agent where messages and data are exchanged, building up shared context over time. In AI Transport, sessions are designed to persist beyond the boundaries of individual connections, enabling modern AI experiences where users expect to:
+
+- Resume conversations across devices: Start a conversation on mobile and seamlessly continue on desktop with full context preserved
+- Return to long-running work: Close the browser while agents continue processing in the background, delivering results when you return
+- Recover from interruptions: Experience connection drops, browser refreshes, or network instability without losing conversation progress
+- Collaborate in shared sessions: Multiple users can participate in the same conversation simultaneously and remain in sync
+
+These capabilities represent a fundamental shift from traditional request/response AI experiences to continuous, resumable interactions that are accessible across all user devices and locations. Sessions have a lifecycle: they begin when a user starts interacting with an agent, remain active while the interaction continues, and can persist even when users disconnect - enabling truly asynchronous AI workflows.
+
+Managing this lifecycle in AI Transport's decoupled architecture involves detecting when users are present, deciding when to stop or continue agent work, and handling scenarios where users disconnect and return.
+
+## Connection-oriented vs channel-oriented sessions
+
+In traditional connection-oriented architectures, sessions are bound to the lifecycle of a WebSocket or SSE connection:
+
+1. Client opens connection to agent server to establish a session
+2. Agent streams response over the connection
+3. When the connection closes, the session ends
+
+This tight coupling means network interruptions terminate sessions, agents cannot continue work after disconnections, and supporting multiple devices or users introduces significant complexity.
+
+AI Transport uses a channel-oriented model where sessions persist independently of individual connections. Clients and agents communicate through [Channels](/docs/channels):
+
+1. Client sends a single request to agent server to establish a session
+2. Server responds with a unique ID for the session, which is used to identify the channel
+3. All further communication happens over the channel
+
+In this model, sessions are associated with the channel, enabling seamless reconnection, background agent work, and multi-device access without additional complexity.
+
+
+
+
+The channel-oriented model provides key benefits for modern AI applications: sessions maintain continuity in the face of disconnections, users can refresh or navigate back to the ongoing session, multiple users or devices can participate in the same session, and agents can continue long-running or asynchronous workloads even when clients disconnect.
+
+The following table compares how each architecture addresses the engineering challenges of delivering these capabilities:
+
+| Challenge | Connection-oriented sessions | Channel-oriented sessions |
+|-----------|------------------------------|---------------------------|
+| Routing | Agents must track which instance holds each session. Reconnecting clients need routing logic to find the correct agent instance across your infrastructure. | Agents and clients only need the channel name. Ably handles message delivery to all subscribers without agents tracking sessions or implementing routing logic. |
+| Message resume | Agents must buffer sent messages and implement replay logic. When clients reconnect, agents must determine what was missed and retransmit without duplicates or gaps, distinctly for each connection. | When clients reconnect, they automatically receive messages published while disconnected. The channel maintains history without agents implementing buffering or replay logic, eliminating the need for server-side session state. |
+| Abandonment detection | Agents must implement logic to distinguish between brief network interruptions and users who have actually left, so they can decide whether to continue work or clean up resources. | Built-in presence tracking signals when users enter and leave channels, providing clear lifecycle events to agents without custom detection logic. |
+| Multi-user and multi-device | Agents must manage multiple concurrent connections from the same user across devices, or from multiple users in collaborative sessions. This requires tracking connections, synchronizing state, and ensuring all participants receive consistent updates. | Multiple users and devices can connect to the same channel. The channel handles message delivery to all participants, simplifying agent logic for multi-user and multi-device scenarios. |
+
+## Identity in channel-oriented sessions
+
+In connection-oriented architectures, the agent server handles authentication directly when establishing the connection. When the connection is opened, the server verifies credentials and associates the authenticated user identity with that specific connection.
+
+In channel-oriented sessions, agents don't manage connections or handle authentication directly. Instead, your server authenticates users and issues tokens that control their access to channels. Ably enforces these authorization rules and provides verified identity information to agents, giving you powerful capabilities for managing who can participate in sessions and what they can do:
+
+- Verified identity: Agents automatically receive the authenticated identity of message senders, with cryptographic guarantees that identities cannot be spoofed
+- Fine-grained authorization: Control precisely what operations each user can perform on specific channels through fine-grained capabilities
+- Rich user attributes: Pass authenticated user data to agents for personalized behavior without building custom token systems
+- Role-based participation: Distinguish between different types of participants, such as users and agents, to customize behaviour based on their role
diff --git a/src/pages/docs/ai-transport/sessions-identity/online-status.mdx b/src/pages/docs/ai-transport/sessions-identity/online-status.mdx
new file mode 100644
index 0000000000..3e9722d647
--- /dev/null
+++ b/src/pages/docs/ai-transport/sessions-identity/online-status.mdx
@@ -0,0 +1,280 @@
+---
+title: "Online status"
+meta_description: "Use Ably Presence to show which users and agents are currently connected to an AI session"
+meta_keywords: "presence, online status, multi-device, multi-user, session abandonment, async workflows"
+---
+
+Modern AI applications require agents to know when users are online, when they've fully disconnected, and how to handle users connected across multiple devices. Ably's [Presence](/docs/presence-occupancy/presence) feature provides realtime online status with automatic lifecycle management, allowing agents to decide when to continue processing, when to wait for user input, and when to clean up resources. Presence detects which users and agents are currently connected to a session, distinguishes between a single device disconnecting and a user going completely offline, and enables responsive online/offline indicators.
+
+## Why online status matters
+
+In channel-oriented sessions, online status serves several critical purposes:
+
+- Session abandonment detection: Agents need to know when users have fully disconnected to decide whether to continue processing, pause work, or clean up resources. Presence provides reliable signals when all of a user's devices have left the session.
+- Multi-device coordination: A single user can connect from multiple devices simultaneously. Presence tracks each connection separately while maintaining stable identity across devices, allowing you to distinguish between "one device left" and "user completely offline".
+- Agent availability signaling: Clients need to know when agents are online and ready to process requests. Agents can enter presence to advertise availability and leave when they complete work or shut down.
+- Collaborative session awareness: In sessions with multiple users, participants can see who else is currently present. This enables realtime collaboration features and helps users understand the current session context.
+
+## Going online
+
+Use the [`enter()`](/docs/presence-occupancy/presence#enter) method to signal that a user or agent is online. When a client enters presence, they are added to the presence set and identified by their `clientId`. You can optionally include data when entering presence to communicate additional context.
+
+
+
+You have flexibility in when to enter presence. For example, an agent might choose to appear as online only while processing a specific task, or remain present for the duration of the entire session. Users typically enter presence when they connect to a session and remain present until they disconnect.
+
+
+
+For example, a user client can enter presence when joining a session:
+
+
+```javascript
+// Client code
+const channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Enter presence with metadata about the user's device
+await channel.presence.enter({
+ device: "mobile",
+ platform: "ios"
+});
+```
+
+
+Similarly, an agent can enter presence to signal that it's online:
+
+
+```javascript
+// Agent code
+const channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Enter presence with metadata about the agent
+await channel.presence.enter({
+ model: "gpt-4"
+});
+```
+
+
+### Going online from multiple devices
+
+A single user can be present on a channel from multiple devices simultaneously. Ably tracks each connection separately using a unique [`connectionId`](/docs/connect#connection-ids), while maintaining the same [`clientId`](/docs/auth/identified-clients#assign) across all connections.
+
+When a user connects from multiple devices, each device enters presence independently. All connections share the same `clientId` but have different `connectionId` values.
+
+For example, when the user connects from their desktop browser:
+
+
+```javascript
+// Client code (device 1: desktop browser)
+const channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+await channel.presence.enter({ device: "desktop" });
+```
+
+
+And then connects from their mobile app while still connected on desktop:
+
+
+```javascript
+// Client code (device 2: mobile app)
+const channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+await channel.presence.enter({ device: "mobile" });
+```
+
+
+Both devices are now members of the presence set with the same `clientId` but different `connectionId` values. When you query the presence set, you'll see two separate entries:
+
+
+```javascript
+// Query presence to see both devices
+const members = await channel.presence.get();
+for (const { clientId, connectionId, data } of members) {
+ console.log(clientId, connectionId, data);
+}
+// Example output:
+// user-123 hd67s4!abcdef-0 { device: "desktop" }
+// user-123 hd67s4!ghijkl-1 { device: "mobile" }
+```
+
+
+When either device leaves or disconnects, the other device remains in the presence set.
+
+## Going offline
+
+Clients can go offline in two ways: explicitly by calling the leave method, or automatically when Ably detects a disconnection.
+
+### Explicitly going offline
+
+Use the [`leave()`](/docs/presence-occupancy/presence#leave) method when a user or agent wants to mark themselves as offline. This immediately notifies presence subscribers on the channel and removes the entry from the presence set, even if they remain connected to Ably.
+
+
+
+For example, a user client can explicitly leave presence:
+
+
+```javascript
+// Client code
+const channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Leave presence when the user marks themselves offline
+await channel.presence.leave();
+```
+
+
+Similarly, an agent can leave presence when it completes its work or shuts down:
+
+
+```javascript
+// Agent code
+const channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Leave presence when the agent shuts down
+await channel.presence.leave();
+```
+
+
+Optionally include data when leaving presence to communicate the reason for going offline. This data is delivered to presence subscribers listening to `leave` events and is also available in [presence history](/docs/presence-occupancy/presence#history):
+
+
+```javascript
+// Leave with a reason
+await channel.presence.leave({
+ reason: "session-completed",
+ timestamp: Date.now()
+});
+```
+
+
+Subscribers receive the `leave` data in the presence message:
+
+
+```javascript
+// Subscribe to leave events to see why members left
+await channel.presence.subscribe("leave", (presenceMessage) => {
+ console.log(`${presenceMessage.clientId} left`);
+ if (presenceMessage.data) {
+ console.log(`Reason: ${presenceMessage.data.reason}`);
+ }
+});
+```
+
+
+### Going offline after disconnection
+
+When a client loses connection unexpectedly, Ably detects the lost connection and automatically leaves the client from the presence set.
+
+By default, clients remain present for 15 seconds after an abrupt disconnection. This prevents excessive enter/leave events during brief network interruptions. If the client reconnects within this window, they remain in the presence set without triggering leave and reenter events.
+
+Use the `transportParams` [client option](/docs/api/realtime-sdk#client-options) to configure disconnection detection and presence lifecycle behaviour. After an abrupt disconnection, the `heartbeatInterval` transport parameter controls how quickly Ably detects the dead connection, while the `remainPresentFor` option controls how long the member is kept in presence before Ably emits the leave event.
+
+
+
+For example, if implementing resumable agents using techniques such as durable execution, configure a longer `remainPresentFor` period to allow time for the new agent instance to come online and resume processing before the previous instance appears as offline. This provides a seamless handoff:
+
+
+```javascript
+// Agent code
+const ably = new Ably.Realtime({
+ key: "{{API_KEY}}",
+ clientId: "weather-agent",
+ // Allow 30 seconds for agent resume and reconnection
+ transportParams: {
+ remainPresentFor: 30000
+ }
+});
+```
+
+
+## Viewing who is online
+
+Participants in a session can query the current presence set or subscribe to presence events to see who else is online and react to changes in realtime. Users might want to see which agents are processing work, while agents might want to detect when specific users are offline to pause or cancel work.
+
+
+
+### Retrieving current presence members
+
+Use [`presence.get()`](/docs/api/realtime-sdk/presence#get) to retrieve the current list of users and agents in the session. Each presence member is uniquely identified by the combination of their `clientId` and `connectionId`. This is useful for showing who is currently available or checking if a specific participant is online before taking action.
+
+
+```javascript
+// Get all currently present members
+const members = await channel.presence.get();
+
+// Display each member - the same user will appear once per distinct connection
+members.forEach((member) => {
+ console.log(`${member.clientId} (connection: ${member.connectionId})`);
+});
+```
+
+
+### Subscribing to presence changes
+
+Use [`presence.subscribe()`](/docs/api/realtime-sdk/presence#subscribe) to receive realtime notifications when users or agents enter or leave the session. This enables building responsive UIs that show online users, or implementing agent logic that reacts to user connectivity changes.
+
+
+```javascript
+// Client code
+const channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Subscribe to changes to the presence set
+await channel.presence.subscribe(async (presenceMessage) => {
+ // Get the current synced presence set after any change
+ const members = await channel.presence.get();
+
+ // Display each member - the same user will appear once per distinct connection
+ members.forEach((member) => {
+ console.log(`${member.clientId} (connection: ${member.connectionId})`);
+ });
+});
+```
+
+
+You can also subscribe to specific presence events:
+
+
+```javascript
+// Subscribe only to enter events
+await channel.presence.subscribe("enter", (presenceMessage) => {
+ console.log(`${presenceMessage.clientId} joined on connection ${presenceMessage.connectionId}`);
+});
+
+// Subscribe only to leave events
+await channel.presence.subscribe("leave", (presenceMessage) => {
+ console.log(`${presenceMessage.clientId} left on connection ${presenceMessage.connectionId}`);
+});
+```
+
+
+### Detecting when a user is offline on all devices
+
+Agents can monitor presence changes to detect when a specific user has gone completely offline across all devices. This is useful for deciding whether to pause expensive operations, cancel ongoing work, deprioritize tasks, or schedule work for later.
+
+
+```javascript
+// Agent code
+const channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+await channel.presence.subscribe(async (presenceMessage) => {
+ // Get the current synced presence set
+ const members = await channel.presence.get();
+
+ // Check if all clients are offline
+ if (members.length === 0) {
+ console.log(`All clients are offline`);
+ }
+
+ // Check if a specific client is offline
+ if (!members.map(m => m.clientId).includes(targetUserId)) {
+ console.log(`${targetUserId} is now offline on all devices`);
+ }
+});
+```
+
diff --git a/src/pages/docs/ai-transport/sessions-identity/resuming-sessions.mdx b/src/pages/docs/ai-transport/sessions-identity/resuming-sessions.mdx
new file mode 100644
index 0000000000..56c99c93d4
--- /dev/null
+++ b/src/pages/docs/ai-transport/sessions-identity/resuming-sessions.mdx
@@ -0,0 +1,140 @@
+---
+title: Resuming sessions
+description: How clients and agents reconnect to ongoing AI Transport sessions after network interruptions or service restarts
+meta_keywords: "session resumption, reconnection, hydration, presence sync, conversation history, channel history, untilAttach, durable execution, agent restart, message recovery, failover"
+---
+
+AI Transport uses a channel-oriented model where sessions persist independently of individual connections. Both users and agents can disconnect and rejoin without ending the session. When users or agents rejoin, they need to resume the session from where they left off.
+
+An agent or user might resume an existing session when:
+
+- A user goes offline or navigates away before returning, expecting to see the latest conversation state
+- An agent goes offline and comes back online when the user returns
+- An agent resumes after a failover or service restart
+
+## Hydrating presence
+
+When you attach to a channel, Ably automatically syncs the complete current presence set to your client. You can then query the presence set or subscribe to presence events without any additional hydration steps. This works the same way for both users and agents.
+
+For details on obtaining the synced presence set, see [Viewing who is online](/docs/ai-transport/sessions-and-identity/online-status#viewing-presence).
+
+## User resumes a session
+
+Users resume by reattaching to the same session channel and hydrating the conversation transcript, in-progress model output, or other session state.
+
+### Hydrating conversation history
+
+The hydration strategy you choose depends on your application model and your chosen approach to token streaming. Clients typically hydrate conversation state using one of these patterns:
+
+- Hydrate entirely from the channel: Use [rewind](/docs/channels/options/rewind) or [history](/docs/storage-history/history) to obtain previous messages on the channel.
+- Hydrate in-progress responses from the channel: Load completed messages from your database and catch up on any in-progress responses from the channel.
+
+For detailed examples of hydrating the token stream, see the token streaming documentation:
+- [Message-per-response hydration](/docs/ai-transport/token-streaming/message-per-response#hydration)
+- [Message-per-token hydration](/docs/ai-transport/token-streaming/message-per-token#hydration)
+
+## Agent resumes a session
+
+When an agent restarts, it needs to resume from where it left off. This involves two distinct concerns:
+
+1. Recovering the agent's execution state: The current step in the workflow, local variables, function call results, pending operations, and any other state needed to continue execution. This state is internal to the agent and typically not visible to users.
+
+2. Catching up on session activity: Any user messages, events, or other activity that occurred while the agent was offline.
+
+These are separate problems requiring different solutions. Agent execution state is handled by your application and you choose how to persist and restore the internal state your agent needs to resume.
+
+
+
+Ably provides access to channel message history, enabling agents to retrieve any messages sent while they were offline. When your agent comes back online, it reattaches to the same channel and catches up on messages it missed. This channel-oriented model provides several key benefits:
+
+- Guaranteed message delivery: Clients can continue publishing messages even while the agent faults and relocates since the channel exists independently of the agent
+- Reliable catch-up: The agent can retrieve any messages published during the interim when it comes back online
+- Ordered delivery: Messages are delivered in the order they were published, ensuring agents process events in the correct sequence
+- Channel-based addressing: The agent only needs the channel name to reconnect, no need to track individual client connections or manage connection state
+
+### Catching up on messages using history
+
+When an agent resumes, it needs to retrieve messages published while it was offline. Use [channel history](/docs/storage-history/history) with the [`untilAttach` option](/docs/storage-history/history#continuous-history) to catch up on historical messages while preserving continuity with live message delivery.
+
+
+
+#### Persisted session state
+
+Your agent should persist the following state to enable resumption:
+
+- Channel name: The channel the agent was processing
+- Last processed timestamp: The timestamp of the last message successfully processed by the agent
+
+This state allows the agent to reconnect to the correct channel and retrieve only the messages it missed.
+
+#### Catching up with continuity
+
+The recommended pattern uses `untilAttach` to paginate backwards through history while maintaining continuity with live message delivery. This ensures no messages are lost between history retrieval and subscription.
+
+
+
+
+```javascript
+// Agent code
+import * as Ably from 'ably';
+
+const ably = new Ably.Realtime({
+ key: process.env.ABLY_API_KEY,
+ clientId: 'agent:assistant'
+});
+
+// Load persisted session state
+const channelName = await loadChannelName();
+const lastProcessedTimestamp = await loadLastProcessedTimestamp();
+
+// Use a channel in a namespace with persistence enabled
+// to access more than 2 minutes of message history
+const channel = ably.channels.get(channelName);
+
+// Subscribe to live messages (implicitly attaches the channel)
+await channel.subscribe('prompt', (message) => {
+ // Process the live message
+ processMessage(message);
+
+ // Persist the timestamp after successful processing
+ saveLastProcessedTimestamp(message.timestamp);
+});
+
+// Fetch history up until the point of attachment, starting from last checkpoint
+let page = await channel.history({
+ untilAttach: true,
+ start: lastProcessedTimestamp,
+ direction: 'forwards'
+});
+
+// Paginate through all missed messages
+while (page) {
+ for (const message of page.items) {
+ // Process the historical message
+ await processMessage(message);
+
+ // Persist the timestamp after successful processing
+ await saveLastProcessedTimestamp(message.timestamp);
+ }
+
+ // Move to next page if available
+ page = page.hasNext() ? await page.next() : null;
+}
+```
+
+
+
+
+This pattern provides guaranteed continuity between historical and live message processing by ensuring that:
+
+1. The subscription starts receiving live messages immediately when you subscribe
+2. History retrieval stops exactly at the point the channel attached
+3. No messages are lost between the end of history and the start of live delivery
diff --git a/src/pages/docs/ai-transport/token-streaming/index.mdx b/src/pages/docs/ai-transport/token-streaming/index.mdx
new file mode 100644
index 0000000000..9dfa3030b0
--- /dev/null
+++ b/src/pages/docs/ai-transport/token-streaming/index.mdx
@@ -0,0 +1,93 @@
+---
+title: Token streaming
+meta_description: "Learn about token streaming with Ably AI Transport, including common patterns and the features provided by the Ably solution."
+---
+
+Ably AI Transport provides a drop-in infrastructure layer that transforms brittle HTTP token streams into resilient, multi-device AI experiences.
+
+## What is token streaming?
+
+Token streaming delivers LLM responses progressively as each token is generated, rather than waiting for the complete response. Users see text appear incrementally, similar to watching someone type in realtime, which creates responsive, engaging AI experiences.
+
+This is the foundation of modern conversational AI, from chatbots to code assistants. User expectations for AI experiences are continually rising and they now expect to:
+
+- Recover from interruptions: Experience connection drops, browser refreshes, or network instability without losing conversation progress or having to restart the task
+- Resume conversations across devices: Start a conversation on mobile and seamlessly continue on desktop with full context preserved
+- Return to long-running work: Close the browser while agents continue processing in the background, receiving results when they return
+- Collaborate in shared sessions: Multiple users can participate in the same conversation simultaneously and remain in sync
+
+## Why HTTP token streaming falls short
+
+Standard HTTP token streaming creates a direct pipeline between your agent and the user's browser. This works well under ideal conditions, but if a client loses network connectivity, switches tabs, or experiences a browser crash then all tokens transmitted during the interruption are lost. Users must restart their request and wait for the model to regenerate the entire response.
+
+These failures frustrate users and waste compute resources. Every dropped stream means paying for tokens that never reached the user.
+
+Ably AI Transport solves this by decoupling token delivery from connection state. Tokens stream to a [Pub/Sub channel](/docs/channels) that persists independently of both client and agent connections.
+
+1. Client sends a single request to agent server to establish a session
+2. Server responds with a unique ID for the session, which is used to identify the channel
+3. All further communication happens over the channel
+
+
+
+
+Dropping in AI Transport to handle the token stream completely changes the user's experience of device switching and failures. You do not need to add complex failure-handling code to your application or deploy additional infrastructure.
+
+| Scenario | HTTP streaming result | Ably AI Transport result |
+|----------|----------------------|--------------------------|
+| Network interruption | Tokens lost, request must restart | Client reconnects automatically and receives missed tokens |
+| User switches tabs | Stream may be throttled or dropped | Stream continues, tokens buffered for delivery |
+| User reloads page | All progress lost, task must be restarted | New session hydrates with complete history, including in-progress response |
+| User switches device | No continuity | New device receives full conversation state, including in-progress response |
+| Mobile network handoff | Connection drops, tokens lost | Seamless recovery within milliseconds, no missed tokens |
+| Multi-user session | Agent must stream to a connection per-user | Agent publishes to single channel, all subscribed users receive the response |
+
+The Ably platform guarantees that messages from a given realtime publisher are [delivered in order](/docs/platform/architecture/message-ordering#ordering-guarantees) and [exactly once](/docs/platform/architecture/idempotency). Your client application does not need to handle duplicate or out-of-order tokens.
+
+## Token streaming patterns
+
+Ably AI Transport is built on the Pub/Sub messaging platform, giving you flexibility to structure messages and channels for your specific use case. AI Transport supports two token streaming patterns using a [Realtime](/docs/api/realtime-sdk) client, each optimized for different requirements.
+
+The Realtime client maintains a persistent connection to the Ably service, enabling high message rates with the lowest possible latencies while preserving delivery guarantees. For more information, see [Realtime and REST](/docs/basics#realtime-and-rest).
+
+### Message-per-response
+
+[Message-per-response](/docs/ai-transport/token-streaming/message-per-response) streams tokens as they arrive while maintaining a clean, compacted message history. Each LLM response becomes a single message on an Ably channel that grows as tokens are appended. This results in efficient storage and straightforward retrieval of complete responses.
+
+This pattern is the recommended approach for most applications. It excels when:
+
+- Clients joining mid-stream need to catch up efficiently without receiving thousands of individual token messages
+- Applications maintain long conversation histories that must load efficiently on new or reconnecting devices
+
+Example use cases:
+
+- Chat experiences: Replay full conversation history when users change devices or when new participants join, allowing both users and agents to maintain context.
+- Long-running and asynchronous tasks: Users reconnect to check progress throughout a task's lifetime without needing to receive the tokens that make up the response individually.
+- Backend-stored responses: Complete responses persist in your database for loading history, while Ably handles realtime delivery of in-progress output.
+
+### Message-per-token
+
+[Message-per-token](/docs/ai-transport/token-streaming/message-per-token) publishes every generated token as an independent Ably message. Each token appears as a separate message in channel history.
+
+This pattern is useful when:
+
+- Clients only need the most recent portion of a response
+- You treat channel history as a short sliding window rather than a full conversation log
+- You need to preserve the specific token fragmentation generated by the model
+
+Example use cases:
+
+- Live transcription, captioning, or translation: Viewers joining a live stream need only enough tokens for the current subtitle frame, not the entire transcript.
+- Code assistance in an editor: Streamed tokens become part of the file on disk as users accept them, so past tokens do not need to be replayed.
+- Autocomplete: Each user edit triggers a fresh response stream, with only the latest suggestion being relevant.
+
+## Message events
+
+Different models and frameworks use different events to signal streaming state, for example start events, stop events, tool calls, and content deltas. When you publish a message to an Ably [channel](/docs/channels), you can set the [message name](/docs/messages#properties) to the event type your client expects, or encode the information in message [`extras`](/docs/messages#properties) or within the payload itself. This allows your frontend to handle each event type appropriately without parsing message content.
+
+## Next steps
+
+- Implement token streaming with [message-per-response](/docs/ai-transport/token-streaming/message-per-response) (recommended for most applications)
+- Implement token streaming with [message-per-token](/docs/ai-transport/token-streaming/message-per-token) for sliding-window use cases
+- Explore the [guides](/docs/guides/ai-transport/openai-message-per-response) for integration with specific models and frameworks
+- Learn about [sessions and identity](/docs/ai-transport/sessions-identity) in AI Transport applications
diff --git a/src/pages/docs/ai-transport/token-streaming/message-per-response.mdx b/src/pages/docs/ai-transport/token-streaming/message-per-response.mdx
new file mode 100644
index 0000000000..e00bacb047
--- /dev/null
+++ b/src/pages/docs/ai-transport/token-streaming/message-per-response.mdx
@@ -0,0 +1,440 @@
+---
+title: Message per response
+meta_description: "Stream individual tokens from AI models into a single message over Ably."
+---
+
+Token streaming with message-per-response is a pattern where every token generated by your model for a given response is appended to a single Ably message. Each complete AI response then appears as one message in the channel history while delivering live tokens in realtime. This uses [Ably Pub/Sub](/docs/basics) for realtime communication between agents and clients.
+
+This pattern is useful for chat-style applications where you want each complete AI response stored as a single message in history, making it easy to retrieve and display multi-response conversation history. Each agent response becomes a single message that grows as tokens are appended, allowing clients joining mid-stream to catch up efficiently without processing thousands of individual tokens.
+
+The message-per-response pattern includes [automatic rate limit protection](/docs/ai-transport/token-rate-limits#per-response) through rollups, making it the recommended approach for most token streaming use cases.
+
+## How it works
+
+1. **Initial message**: When an agent response begins, publish an initial message with `message.create` action to the Ably channel with an empty or the first token as content.
+2. **Token streaming**: Append subsequent tokens to the original message by publishing those tokens with the `message.append` action.
+3. **Live delivery**: Clients subscribed to the channel receive each appended token in realtime, allowing them to progressively render the response.
+4. **Compacted history**: The channel history contains only one message per agent response, which includes all tokens appended to it concatenated together.
+
+You do not need to mark the message or token stream as completed; the final message content automatically includes the full response constructed from all appended tokens.
+
+
+
+## Enable appends
+
+Message append functionality requires "Message annotations, updates, deletes and appends" to be enabled in a [channel rule](/docs/channels#rules) associated with the channel.
+
+
+
+To enable the channel rule:
+
+1. Go to the [Ably dashboard](https://www.ably.com/dashboard) and select your app.
+2. Navigate to the "Configuration" > "Rules" section from the left-hand navigation bar.
+3. Choose "Add new rule".
+4. Enter a channel name or namespace pattern (e.g. `ai` for all channels starting with `ai:`).
+5. Select the "Message annotations, updates, deletes and appends" option from the list.
+6. Click "Create channel rule".
+
+The examples on this page use the `ai:` namespace prefix, which assumes you have configured the rule for `ai`.
+
+## Publishing tokens
+
+Publish tokens from a [Realtime](/docs/api/realtime-sdk) client, which maintains a persistent connection to the Ably service. This allows you to publish at very high message rates with the lowest possible latencies, while preserving guarantees around message delivery order. For more information, see [Realtime and REST](/docs/basics#realtime-and-rest).
+
+[Channels](/docs/channels) separate message traffic into different topics. For token streaming, each conversation or session typically has its own channel.
+
+Use the [`get()`](/docs/api/realtime-sdk/channels#get) method to create or retrieve a channel instance:
+
+
+```javascript
+const channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}');
+```
+
+
+To start streaming an AI response, publish the initial message. The message is identified by a server-assigned identifier called a [`serial`](/docs/messages#properties). Use the `serial` to append each subsequent token to the message as it arrives from the AI model:
+
+
+```javascript
+// Publish initial message and capture the serial for appending tokens
+const { serials: [msgSerial] } = await channel.publish('response', { data: '' });
+
+// Example: stream returns events like { type: 'token', text: 'Hello' }
+for await (const event of stream) {
+ // Append each token as it arrives
+ if (event.type === 'token') {
+ channel.appendMessage({ serial: msgSerial, data: event.text });
+ }
+}
+```
+
+
+When publishing tokens, don't await the `channel.appendMessage()` call. Ably rolls up acknowledgments and debounces them for efficiency, which means awaiting each append would unnecessarily slow down your token stream. Messages are still published in the order that `appendMessage()` is called, so delivery order is not affected.
+
+
+```javascript
+// ✅ Do this - append without await for maximum throughput
+for await (const event of stream) {
+ if (event.type === 'token') {
+ channel.appendMessage({ serial: msgSerial, data: event.text });
+ }
+}
+
+// ❌ Don't do this - awaiting each append reduces throughput
+for await (const event of stream) {
+ if (event.type === 'token') {
+ await channel.appendMessage({ serial: msgSerial, data: event.text });
+ }
+}
+```
+
+
+
+
+
+
+This pattern allows publishing append operations for multiple concurrent model responses on the same channel. As long as you append to the correct message serial, tokens from different responses will not interfere with each other, and the final concatenated message for each response will contain only the tokens from that response.
+
+### Configuring rollup behaviour
+
+By default, AI Transport automatically rolls up tokens into messages at a rate of 25 messages per second (using a 40ms rollup window). This protects you from hitting connection rate limits while maintaining a smooth user experience. You can tune this behaviour when establishing your connection to balance between message costs and delivery speed:
+
+
+```javascript
+const realtime = new Ably.Realtime({
+ key: 'your-api-key',
+ transportParams: { appendRollupWindow: 100 } // 10 messages/s
+});
+```
+
+
+The `appendRollupWindow` parameter controls how many tokens are combined into each published message for a given model output rate. This creates a trade-off between delivery smoothness and the number of concurrent model responses you can stream on a single connection:
+
+- With a shorter rollup window, tokens are published more frequently, creating a smoother, more fluid experience for users as they see the response appear in more fine-grained chunks. However, this consumes more of your [connection's message rate capacity](/docs/platform/pricing/limits#connection), limiting how many simultaneous model responses you can stream.
+- With a longer rollup window, multiple tokens are batched together into fewer messages, allowing you to run more concurrent response streams on the same connection, but users will notice tokens arriving in larger chunks.
+
+The default 40ms window strikes a balance, delivering tokens at 25 messages per second - smooth enough for a great user experience while allowing you to run two simultaneous response streams on a single connection. If you need to support more concurrent streams, increase the rollup window (up to 500ms), accepting that tokens will arrive in more noticeable batches. Alternatively, instantiate a separate Ably client which uses its own connection, giving you access to additional message rate capacity.
+
+
+
+## Subscribing to token streams
+
+Subscribers receive different message actions depending on when they join and how they're retrieving messages. Each message has an `action` field that indicates how to process it, and a `serial` field that identifies which message the action relates to:
+
+- `message.create`: Indicates a new response has started (i.e. a new message was created). The message `data` contains the initial content (often empty or the first token). Store this as the beginning of a new response using `serial` as the identifier.
+- `message.append`: Contains a single token fragment to append. The message `data` contains only the new token, not the full concatenated response. Append this token to the existing response identified by `serial`.
+- `message.update`: Contains the whole response up to that point. The message `data` contains the full concatenated text so far. Replace the entire response content with this data for the message identified by `serial`. This action occurs when the channel needs to resynchronize the full message state, such as after a client [resumes](/docs/connect/states#resume) from a transient disconnection.
+
+
+```javascript
+const channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}');
+
+// Track responses by message serial
+const responses = new Map();
+
+// Subscribe to live messages (implicitly attaches the channel)
+await channel.subscribe((message) => {
+ switch (message.action) {
+ case 'message.create':
+ // New response started
+ responses.set(message.serial, message.data);
+ break;
+ case 'message.append':
+ // Append token to existing response
+ const current = responses.get(message.serial) || '';
+ responses.set(message.serial, current + message.data);
+ break;
+ case 'message.update':
+ // Replace entire response content
+ responses.set(message.serial, message.data);
+ break;
+ }
+});
+```
+
+
+## Client hydration
+
+When clients connect or reconnect, such as after a page refresh, they often need to catch up on complete responses and individual tokens that were published while they were offline or before they joined.
+
+The message per response pattern enables efficient client state hydration without needing to process every individual token and supports seamlessly transitioning from historical responses to live tokens.
+
+
+
+### Using rewind for recent history
+
+The simplest approach is to use Ably's [rewind](/docs/channels/options/rewind) channel option to attach to the channel at some point in the recent past, and automatically receive all messages since that point. Historical messages are delivered as `message.update` events containing the complete concatenated response, which then seamlessly transition to live `message.append` events for any ongoing responses:
+
+
+```javascript
+// Use rewind to receive recent historical messages
+const channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}', {
+ params: { rewind: '2m' } // or rewind: '10' for message count
+});
+
+// Track responses by message serial
+const responses = new Map();
+
+// Subscribe to receive both recent historical and live messages,
+// which are delivered in order to the subscription
+await channel.subscribe((message) => {
+ switch (message.action) {
+ case 'message.create':
+ // New response started
+ responses.set(message.serial, message.data);
+ break;
+ case 'message.append':
+ // Append token to existing response
+ const current = responses.get(message.serial) || '';
+ responses.set(message.serial, current + message.data);
+ break;
+ case 'message.update':
+ // Replace entire response content
+ responses.set(message.serial, message.data);
+ break;
+ }
+});
+```
+
+
+Rewind supports two formats:
+
+- **Time-based**: Use a time interval like `'30s'` or `'2m'` to retrieve messages from that time period
+- **Count-based**: Use a number like `10` or `50` to retrieve the most recent N messages (maximum 100)
+
+
+
+### Using history for older messages
+
+Use [channel history](/docs/storage-history/history) with the [`untilAttach` option](/docs/storage-history/history#continuous-history) to paginate back through history to obtain historical responses, while preserving continuity with the delivery of live tokens:
+
+
+```javascript
+const channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}');
+
+// Track responses by message serial
+const responses = new Map();
+
+// Subscribe to live messages (implicitly attaches the channel)
+await channel.subscribe((message) => {
+ switch (message.action) {
+ case 'message.create':
+ // New response started
+ responses.set(message.serial, message.data);
+ break;
+ case 'message.append':
+ // Append token to existing response
+ const current = responses.get(message.serial) || '';
+ responses.set(message.serial, current + message.data);
+ break;
+ case 'message.update':
+ // Replace entire response content
+ responses.set(message.serial, message.data);
+ break;
+ }
+});
+
+// Fetch history up until the point of attachment
+let page = await channel.history({ untilAttach: true });
+
+// Paginate backwards through history
+while (page) {
+ // Messages are newest-first
+ for (const message of page.items) {
+ // message.data contains the full concatenated text
+ responses.set(message.serial, message.data);
+ }
+
+ // Move to next page if available
+ page = page.hasNext() ? await page.next() : null;
+}
+```
+
+
+### Hydrating an in-progress response
+
+A common pattern is to persist complete model responses in your database while using Ably for streaming in-progress responses.
+
+The client loads completed responses from your database, then uses Ably to catch up on any response that was still in progress.
+
+You can hydrate in-progress responses using either the [rewind](#rewind) or [history](#history) pattern.
+
+#### Publishing with correlation metadata
+
+To correlate Ably messages with your database records, include the `responseId` in the message [`extras`](/docs/messages#properties) when publishing:
+
+
+```javascript
+// Publish initial message with responseId in extras
+const { serials: [msgSerial] } = await channel.publish({
+ name: 'response',
+ data: '',
+ extras: {
+ headers: {
+ responseId: 'resp_abc123' // Your database response ID
+ }
+ }
+});
+
+// Append tokens, including extras to preserve headers
+for await (const event of stream) {
+ if (event.type === 'token') {
+ channel.appendMessage({ serial: msgSerial, data: event.text, extras: {
+ headers: {
+ responseId: 'resp_abc123'
+ }
+ }});
+ }
+}
+```
+
+
+
+
+#### Hydrate using rewind
+
+When hydrating, load completed responses from your database, then use [rewind](/docs/channels/options/rewind) to catch up on any in-progress response. Check the `responseId` from message extras to skip responses already loaded from your database:
+
+
+```javascript
+// Load completed responses from your database
+// completedResponses is a Set of responseIds
+const completedResponses = await loadResponsesFromDatabase();
+
+// Use rewind to receive recent historical messages
+const channel = realtime.channels.get('ai:responses', {
+ params: { rewind: '2m' }
+});
+
+// Track in-progress responses by responseId
+const inProgressResponses = new Map();
+
+await channel.subscribe((message) => {
+ const responseId = message.extras?.headers?.responseId;
+
+ if (!responseId) {
+ console.warn('Message missing responseId');
+ return;
+ }
+
+ // Skip messages for responses already loaded from database
+ if (completedResponses.has(responseId)) {
+ return;
+ }
+
+ switch (message.action) {
+ case 'message.create':
+ // New response started
+ inProgressResponses.set(responseId, message.data);
+ break;
+ case 'message.append':
+ // Append token to existing response
+ const current = inProgressResponses.get(responseId) || '';
+ inProgressResponses.set(responseId, current + message.data);
+ break;
+ case 'message.update':
+ // Replace entire response content
+ inProgressResponses.set(responseId, message.data);
+ break;
+ }
+});
+```
+
+
+
+
+#### Hydrate using history
+
+Load completed responses from your database, then use [channel history](/docs/storage-history/history) with the [`untilAttach` option](/docs/storage-history/history#continuous-history) to catch up on any in-progress responses. Use the timestamp of the last completed response to start pagination from that point forward, ensuring continuity with live message delivery.
+
+
+```javascript
+// Load completed responses from database (sorted by timestamp, oldest first)
+const completedResponses = await loadResponsesFromDatabase();
+
+// Get the timestamp of the latest completed response
+const latestTimestamp = completedResponses.latest().timestamp;
+
+const channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}');
+
+// Track in progress responses by ID
+const inProgressResponses = new Map();
+
+// Subscribe to live messages (implicitly attaches)
+await channel.subscribe((message) => {
+ const responseId = message.extras?.headers?.responseId;
+
+ if (!responseId) {
+ console.warn('Message missing responseId');
+ return;
+ }
+
+ // Skip messages for responses already loaded from database
+ if (completedResponses.has(responseId)) {
+ return;
+ }
+
+ switch (message.action) {
+ case 'message.create':
+ // New response started
+ inProgressResponses.set(responseId, message.data);
+ break;
+ case 'message.append':
+ // Append token to existing response
+ const current = inProgressResponses.get(responseId) || '';
+ inProgressResponses.set(responseId, current + message.data);
+ break;
+ case 'message.update':
+ // Replace entire response content
+ inProgressResponses.set(responseId, message.data);
+ break;
+ }
+});
+
+// Fetch history from the last completed response until attachment
+let page = await channel.history({
+ untilAttach: true,
+ start: latestTimestamp,
+ direction: 'forwards'
+});
+
+// Paginate through all missed messages
+while (page) {
+ for (const message of page.items) {
+ const responseId = message.extras?.headers?.responseId;
+
+ if (!responseId) {
+ console.warn('Message missing responseId');
+ continue;
+ }
+
+ // message.data contains the full concatenated text so far
+ inProgressResponses.set(responseId, message.data);
+ }
+
+ // Move to next page if available
+ page = page.hasNext() ? await page.next() : null;
+}
+```
+
+
+
diff --git a/src/pages/docs/ai-transport/token-streaming/message-per-token.mdx b/src/pages/docs/ai-transport/token-streaming/message-per-token.mdx
new file mode 100644
index 0000000000..8ea595cfc6
--- /dev/null
+++ b/src/pages/docs/ai-transport/token-streaming/message-per-token.mdx
@@ -0,0 +1,441 @@
+---
+title: Message per token
+meta_description: "Stream individual tokens from AI models as separate messages over Ably."
+---
+
+Token streaming with message-per-token is a pattern where every token generated by your model is published as an independent Ably message. Each token then appears as one message in the channel history. This uses [Ably Pub/Sub](/docs/basics) for realtime communication between agents and clients.
+
+This pattern is useful when clients only care about the most recent part of a response and you are happy to treat the channel history as a short sliding window rather than a full conversation log. For example:
+
+- Backend-stored responses: The backend writes complete responses to a database and clients load those full responses from there, while Ably is used only to deliver live tokens for the current in-progress response.
+- Live transcription, captioning, or translation: A viewer who joins a live stream only needs sufficient tokens for the current "frame" of subtitles, not the entire transcript so far.
+- Code assistance in an editor: Streamed tokens become part of the file on disk as they are accepted, so past tokens do not need to be replayed from Ably.
+- Autocomplete: A fresh response is streamed for each change a user makes to a document, with only the latest suggestion being relevant.
+
+## Publishing tokens
+
+Publish tokens from a [Realtime](/docs/api/realtime-sdk) client, which maintains a persistent connection to the Ably service. This allows you to publish at very high message rates with the lowest possible latencies, while preserving guarantees around message delivery order. For more information, see [Realtime and REST](/docs/basics#realtime-and-rest).
+
+[Channels](/docs/channels) separate message traffic into different topics. For token streaming, each conversation or session typically has its own channel.
+
+Use the [`get()`](/docs/api/realtime-sdk/channels#get) method to create or retrieve a channel instance:
+
+
+```javascript
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+```
+
+
+When publishing tokens, don't await the `channel.publish()` call. Ably rolls up acknowledgments and debounces them for efficiency, which means awaiting each publish would unnecessarily slow down your token stream. Messages are still published in the order that `publish()` is called, so delivery order is not affected.
+
+
+```javascript
+// ✅ Do this - publish without await for maximum throughput
+for await (const event of stream) {
+ if (event.type === 'token') {
+ channel.publish('token', event.text);
+ }
+}
+
+// ❌ Don't do this - awaiting each publish reduces throughput
+for await (const event of stream) {
+ if (event.type === 'token') {
+ await channel.publish('token', event.text);
+ }
+}
+```
+
+
+This approach maximizes throughput while maintaining ordering guarantees, allowing you to stream tokens as fast as your AI model generates them.
+
+
+
+
+
+## Streaming patterns
+
+Ably is a pub/sub messaging platform, so you can structure your messages however works best for your application. Below are common patterns for streaming tokens, each showing both agent-side publishing and client-side subscription. Choose the approach that fits your use case, or create your own variation.
+
+### Continuous token stream
+
+For simple streaming scenarios such as live transcription, where all tokens are part of a continuous stream, simply publish each token as a message.
+
+#### Publish tokens
+
+
+```javascript
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+// Example: stream returns events like { type: 'token', text: 'Hello' }
+for await (const event of stream) {
+ if (event.type === 'token') {
+ channel.publish('token', event.text);
+ }
+}
+```
+
+
+#### Subscribe to tokens
+
+
+```javascript
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+// Subscribe to token messages
+await channel.subscribe('token', (message) => {
+ const token = message.data;
+ console.log(token); // log each token as it arrives
+});
+```
+
+
+This pattern is simple and works well when you're displaying a single, continuous stream of tokens.
+
+### Token stream with multiple responses
+
+For applications with multiple responses, such as chat conversations, include a `responseId` in message [`extras`](/docs/messages#properties) to correlate tokens together that belong to the same response.
+
+#### Publish tokens
+
+
+```javascript
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+// Example: stream returns events like { type: 'token', text: 'Hello', responseId: 'resp_abc123' }
+for await (const event of stream) {
+ if (event.type === 'token') {
+ channel.publish({
+ name: 'token',
+ data: event.text,
+ extras: {
+ headers: {
+ responseId: event.responseId
+ }
+ }
+ });
+ }
+}
+```
+
+
+#### Subscribe to tokens
+
+Use the `responseId` header in message extras to correlate tokens. The `responseId` allows you to group tokens belonging to the same response and correctly handle token delivery for distinct responses, even when delivered concurrently.
+
+
+```javascript
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+// Track responses by ID
+const responses = new Map();
+
+await channel.subscribe('token', (message) => {
+ const token = message.data;
+ const responseId = message.extras?.headers?.responseId;
+
+ if (!responseId) {
+ console.warn('Token missing responseId');
+ return;
+ }
+
+ // Create an empty response
+ if (!responses.has(responseId)) {
+ responses.set(responseId, '');
+ }
+
+ // Append token to response
+ responses.set(responseId, responses.get(responseId) + token);
+});
+```
+
+
+### Token stream with explicit start/stop events
+
+In some cases, your AI model response stream may include explicit events to mark response boundaries. You can indicate the event type, such as a response start/stop event, using the Ably message [`name`](/docs/messages#properties).
+
+#### Publish tokens
+
+
+```javascript
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+// Example: stream returns events like:
+// { type: 'message_start', responseId: 'resp_abc123' }
+// { type: 'message_delta', responseId: 'resp_abc123', text: 'Hello' }
+// { type: 'message_stop', responseId: 'resp_abc123' }
+
+for await (const event of stream) {
+ if (event.type === 'message_start') {
+ // Publish response start
+ channel.publish({
+ name: 'start',
+ extras: {
+ headers: {
+ responseId: event.responseId
+ }
+ }
+ });
+ } else if (event.type === 'message_delta') {
+ // Publish tokens
+ channel.publish({
+ name: 'token',
+ data: event.text,
+ extras: {
+ headers: {
+ responseId: event.responseId
+ }
+ }
+ });
+ } else if (event.type === 'message_stop') {
+ // Publish response stop
+ channel.publish({
+ name: 'stop',
+ extras: {
+ headers: {
+ responseId: event.responseId
+ }
+ }
+ });
+ }
+}
+```
+
+
+#### Subscribe to tokens
+
+Handle each event type to manage response lifecycle:
+
+
+```javascript
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+const responses = new Map();
+
+// Handle response start
+await channel.subscribe('start', (message) => {
+ const responseId = message.extras?.headers?.responseId;
+ responses.set(responseId, '');
+});
+
+// Handle tokens
+await channel.subscribe('token', (message) => {
+ const responseId = message.extras?.headers?.responseId;
+ const token = message.data;
+
+ const currentText = responses.get(responseId) || '';
+ responses.set(responseId, currentText + token);
+});
+
+// Handle response stop
+await channel.subscribe('stop', (message) => {
+ const responseId = message.extras?.headers?.responseId;
+ const finalText = responses.get(responseId);
+ console.log('Response complete:', finalText);
+});
+```
+
+
+## Client hydration
+
+When clients connect or reconnect, such as after a page refresh, they often need to catch up on tokens that were published while they were offline or before they joined. Ably provides several approaches to hydrate client state depending on your application's requirements.
+
+
+
+
+
+### Using rewind for recent history
+
+The simplest approach is to use Ably's [rewind](/docs/channels/options/rewind) channel option to attach to the channel at some point in the recent past, and automatically receive all tokens since that point:
+
+
+```javascript
+// Use rewind to receive recent historical messages
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', {
+ params: { rewind: '2m' } // or rewind: 100 for message count
+});
+
+// Subscribe to receive both recent historical and live messages,
+// which are delivered in order to the subscription
+await channel.subscribe('token', (message) => {
+ const token = message.data;
+
+ // Process tokens from both recent history and live stream
+ console.log('Token received:', token);
+});
+```
+
+
+Rewind supports two formats:
+
+- **Time-based**: Use a time interval like `'30s'` or `'2m'` to retrieve messages from that time period
+- **Count-based**: Use a number like `50` or `100` to retrieve the most recent N messages (maximum 100)
+
+
+
+By default, rewind is limited to the last 2 minutes of messages. This is usually sufficient for scenarios where clients need only recent context, such as for continuous token streaming, or when the response stream from a given model request does not exceed 2 minutes. If you need more than 2 minutes of history, see [Using history for longer persistence](#history).
+
+### Using history for older messages
+
+For applications that need to retrieve tokens beyond the 2-minute rewind window, enable [persistence](/docs/storage-history/storage#all-message-persistence) on your channel. Use [channel history](/docs/storage-history/history) with the [`untilAttach` option](/docs/storage-history/history#continuous-history) to paginate back through history to obtain historical tokens, while preserving continuity with the delivery of live tokens:
+
+
+```javascript
+// Use a channel in a namespace called 'persisted', which has persistence enabled
+const channel = realtime.channels.get('persisted:{{RANDOM_CHANNEL_NAME}}');
+
+let response = '';
+
+// Subscribe to live messages (implicitly attaches the channel)
+await channel.subscribe('token', (message) => {
+ // Append the token to the end of the response
+ response += message.data;
+});
+
+// Fetch history up until the point of attachment
+let page = await channel.history({ untilAttach: true });
+
+// Paginate backwards through history
+while (page) {
+ // Messages are newest-first, so prepend them to response
+ for (const message of page.items) {
+ response = message.data + response;
+ }
+
+ // Move to next page if available
+ page = page.hasNext() ? await page.next() : null;
+}
+```
+
+
+### Hydrating an in-progress response
+
+A common pattern is to persist complete model responses in your database while using Ably for live token delivery of the in-progress response.
+
+The client loads completed responses from your database, then reaches back into Ably channel history until it encounters a token for a response it's already loaded.
+
+You can retrieve partial history using either the [rewind](#rewind) or [history](#history) pattern.
+
+#### Hydrate using rewind
+
+Load completed responses from your database, then use rewind to catch up on any in-progress responses, skipping any tokens that belong to a response that was already loaded:
+
+
+```javascript
+// Load completed responses from database
+const completedResponses = await loadResponsesFromDatabase();
+
+// Use rewind to receive recent historical messages
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', {
+ params: { rewind: '2m' }
+});
+
+// Track in progress responses by ID
+const inProgressResponses = new Map();
+
+// Subscribe to receive both recent historical and live messages,
+// which are delivered in order to the subscription
+await channel.subscribe('token', (message) => {
+ const token = message.data;
+ const responseId = message.extras?.headers?.responseId;
+
+ if (!responseId) {
+ console.warn('Token missing responseId');
+ return;
+ }
+
+ // Skip tokens for responses already hydrated from database
+ if (completedResponses.has(responseId)) {
+ return;
+ }
+
+ // Create an empty in-progress response
+ if (!inProgressResponses.has(responseId)) {
+ inProgressResponses.set(responseId, '');
+ }
+
+ // Append tokens for new responses
+ inProgressResponses.set(responseId, inProgressResponses.get(responseId) + token);
+});
+```
+
+
+#### Hydrate using history
+
+Load completed responses from your database, then paginate backwards through history to catch up on in-progress responses until you reach a token that belongs to a response you've already loaded:
+
+
+```javascript
+// Load completed responses from database
+const completedResponses = await loadResponsesFromDatabase();
+
+// Use a channel in a namespace called 'persisted', which has persistence enabled
+const channel = realtime.channels.get('persisted:{{RANDOM_CHANNEL_NAME}}');
+
+// Track in progress responses by ID
+const inProgressResponses = new Map();
+
+// Subscribe to live tokens (implicitly attaches)
+await channel.subscribe('token', (message) => {
+ const token = message.data;
+ const responseId = message.extras?.headers?.responseId;
+
+ if (!responseId) {
+ console.warn('Token missing responseId');
+ return;
+ }
+
+ // Skip tokens for responses already hydrated from database
+ if (completedResponses.has(responseId)) {
+ return;
+ }
+
+ // Create an empty in-progress response
+ if (!inProgressResponses.has(responseId)) {
+ inProgressResponses.set(responseId, '');
+ }
+
+ // Append live tokens for in-progress responses
+ inProgressResponses.set(responseId, inProgressResponses.get(responseId) + token);
+});
+
+// Paginate backwards through history until we encounter a hydrated response
+let page = await channel.history({ untilAttach: true });
+
+// Paginate backwards through history
+let done = false;
+while (page && !done) {
+ // Messages are newest-first, so prepend them to response
+ for (const message of page.items) {
+ const token = message.data;
+ const responseId = message.extras?.headers?.responseId;
+
+ // Stop when we reach a response already loaded from database
+ if (completedResponses.has(responseId)) {
+ done = true;
+ break;
+ }
+
+ // Create an empty in-progress response
+ if (!inProgressResponses.has(responseId)) {
+ inProgressResponses.set(responseId, '');
+ }
+
+ // Prepend historical tokens for in-progress responses
+ inProgressResponses.set(responseId, token + inProgressResponses.get(responseId));
+ }
+
+ // Move to next page if available
+ page = page.hasNext() ? await page.next() : null;
+}
+```
+
diff --git a/src/pages/docs/ai-transport/token-streaming/token-rate-limits.mdx b/src/pages/docs/ai-transport/token-streaming/token-rate-limits.mdx
new file mode 100644
index 0000000000..1efaeb4aaa
--- /dev/null
+++ b/src/pages/docs/ai-transport/token-streaming/token-rate-limits.mdx
@@ -0,0 +1,74 @@
+---
+title: Token streaming limits
+meta_description: "Learn how token streaming interacts with Ably message limits and how to ensure your application delivers consistent performance."
+---
+
+LLM token streaming introduces high-rate or bursty traffic patterns to your application, with some models outputting upwards of 150 distinct events (that is, tokens or response deltas) per second. Output rates can vary unpredictably over the lifetime of a response stream, and you have limited control over third-party model behaviour. AI Transport provides functionality to help you stay within your [rate limits](/docs/platform/pricing/limits) while delivering a great experience to your users.
+
+Ably's limits divide into two categories:
+
+1. Limits relating to usage across an account, such as the total number of messages sent in a month, or the aggregate instantaneous message rate across all connections and channels
+2. Limits relating to the capacity of a single resource, such as a connection or a channel
+
+Limits in the first category exist to provide protection in the case of accidental spikes or deliberate abuse. Provided that your package is sized correctly for your use-case, these limits should not be hit as a result of valid traffic.
+
+The limits in the second category, however, cannot be increased arbitrarily and exist to protect the integrity of the service. The limits associated with individual connections or channels can be relevant to LLM token streaming use-cases. The following sections discuss these limits in particular.
+
+## Message-per-response
+
+The [message-per-response](/docs/ai-transport/features/token-streaming/message-per-response) pattern includes automatic rate limit protection. AI Transport prevents a single response stream from reaching the message rate limit for a connection by rolling up multiple appends into a single published message:
+
+1. Your agent streams tokens to the channel at the model's output rate
+2. Ably publishes the first token immediately, then automatically rolls up subsequent tokens on receipt
+3. Clients receive the same content, delivered in fewer discrete messages
+
+By default, Ably delivers a single response stream at 25 messages per second or the model output rate, whichever is lower. This means you can publish two simultaneous response streams on the same channel or connection with any [Ably package](/docs/platform/pricing#packages), because each stream uses half of the [connection inbound message rate](/docs/platform/pricing/limits#connection). Ably charges for the number of published messages, not for the number of streamed tokens.
+
+### Configure rollup behaviour
+
+Ably concatenates all appends for a single response that are received during the rollup window into one published message. You can specify the rollup window for a particular connection by setting the `appendRollupWindow` [transport parameter](/docs/api/realtime-sdk#client-options). This allows you to determine how much of the connection message rate can be consumed by a single response stream and control your consumption costs.
+
+
+| `appendRollupWindow` | Maximum message rate for a single response |
+|---|---|
+| 0ms | Model output rate |
+| 20ms | 50 messages/s |
+| 40ms *(default)* | 25 messages/s |
+| 100ms | 10 messages/s |
+| 500ms *(max)* | 2 messages/s |
+
+The following example code demonstrates establishing a connection to Ably with `appendRollupWindow` set to 100ms:
+
+
+```javascript
+const ably = new Ably.Realtime(
+ {
+ key: 'your-api-key',
+ transportParams: { appendRollupWindow: 100 }
+ }
+);
+```
+
+
+
+
+## Message-per-token
+
+The [message-per-token](/docs/ai-transport/features/token-streaming/message-per-token) pattern requires you to manage rate limits directly. Each token publishes as a separate message, so high-speed model output can cause per-connection or per-channel rate limits to be hit, as well as consuming overall message allowances quickly.
+
+To stay within limits:
+
+- Calculate your headroom by comparing your model's peak output rate against your package's [connection inbound message rate](/docs/platform/pricing/limits#connection)
+- Account for concurrency by multiplying peak rates by the maximum number of simultaneous streams your application supports
+- If required, batch tokens in your agent before publishing to the SDK, reducing message count while maintaining delivery speed
+- Enable [server-side batching](/docs/messages/batch#server-side) to reduce the number of messages delivered to your subscribers
+
+If your application requires higher message rates than your current package allows, [contact Ably](/contact) to discuss options.
+
+## Next steps
+
+- Review [Ably platform limits](/docs/platform/pricing/limits) to understand rate limit thresholds for your package
+- Learn about the [message-per-response](/docs/ai-transport/features/token-streaming/message-per-response) pattern for automatic rate limit protection
+- Learn about the [message-per-token](/docs/ai-transport/features/token-streaming/message-per-token) pattern for fine-grained control
diff --git a/src/pages/docs/api/realtime-sdk/channels.mdx b/src/pages/docs/api/realtime-sdk/channels.mdx
index d0e98f56d4..08fd44c182 100644
--- a/src/pages/docs/api/realtime-sdk/channels.mdx
+++ b/src/pages/docs/api/realtime-sdk/channels.mdx
@@ -1961,7 +1961,7 @@ The action type of the message, one of the [`MessageAction`](/docs/api/realtime-
### serial
-A server-assigned identifier that will be the same in all future updates of this message. It can be used to add [annotations](/docs/messages/annotations) to a message or to [update or delete](/docs/messages/updates-deletes) it. Serial will only be set if you enable annotations, updates, and deletes in [channel rules](/docs/channels#rules).
+```shell
+mkdir ably-anthropic-example && cd ably-anthropic-example
+npm init -y
+```
+
+
+Install the required packages using NPM:
+
+
+```shell
+npm install @anthropic-ai/sdk@^0.71 ably@^2
+```
+
+
+
+
+Export your Anthropic API key to the environment, which will be used later in the guide by the Anthropic SDK:
+
+
+```shell
+export ANTHROPIC_API_KEY="your_api_key_here"
+```
+
+
+## Step 1: Enable message appends
+
+Message append functionality requires "Message annotations, updates, deletes and appends" to be enabled in a [channel rule](/docs/channels#rules) associated with the channel.
+
+
+
+To enable the channel rule:
+
+1. Go to the [Ably dashboard](https://www.ably.com/dashboard) and select your app.
+2. Navigate to the "Configuration" > "Rules" section from the left-hand navigation bar.
+3. Choose "Add new rule".
+4. Enter a channel name or namespace pattern (e.g. `ai` for all channels starting with `ai:`).
+5. Select the "Message annotations, updates, deletes and appends" option from the list.
+6. Click "Create channel rule".
+
+The examples in this guide use the `ai:` namespace prefix, which assumes you have configured the rule for `ai:*`.
+
+
+
+## Step 2: Get a streamed response from Anthropic
+
+Initialize an Anthropic client and use the [Messages API](https://docs.anthropic.com/en/api/messages) to stream model output as a series of events.
+
+Create a new file `publisher.mjs` with the following contents:
+
+
+```javascript
+import Anthropic from '@anthropic-ai/sdk';
+
+// Initialize Anthropic client
+const anthropic = new Anthropic();
+
+// Process each streaming event
+async function processEvent(event) {
+ console.log(JSON.stringify(event));
+ // This function is updated in the next sections
+}
+
+// Create streaming response from Anthropic
+async function streamAnthropicResponse(prompt) {
+ const stream = await anthropic.messages.create({
+ model: "claude-sonnet-4-5",
+ max_tokens: 1024,
+ messages: [{ role: "user", content: prompt }],
+ stream: true,
+ });
+
+ // Iterate through streaming events
+ for await (const event of stream) {
+ await processEvent(event);
+ }
+}
+
+// Usage example
+streamAnthropicResponse("Tell me a short joke");
+```
+
+
+### Understand Anthropic streaming events
+
+Anthropic's Messages API [streams](https://docs.anthropic.com/en/api/messages-streaming) model output as a series of events when you set `stream: true`. Each streamed event includes a `type` property which describes the event type. A complete text response can be constructed from the following event types:
+
+- [`message_start`](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types): Signals the start of a response. Contains a `message` object with an `id` to correlate subsequent events.
+
+- [`content_block_start`](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types): Indicates the start of a new content block. For text responses, the `content_block` will have `type: "text"`; other types may be specified, such as `"thinking"` for internal reasoning tokens. The `index` indicates the position of this item in the message's `content` array.
+
+- [`content_block_delta`](https://platform.claude.com/docs/en/build-with-claude/streaming#content-block-delta-types): Contains a single text delta in the `delta.text` field. If `delta.type === "text_delta"` the delta contains model response text; other types may be specified, such as `"thinking_delta"` for internal reasoning tokens. Use the `index` to correlate deltas relating to a specific content block.
+
+- [`content_block_stop`](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types): Signals completion of a content block. Contains the `index` that identifies the content block.
+
+- [`message_delta`](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types): Contains additional message-level metadata that may be streamed incrementally. Includes a [`delta.stop_reason`](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons) which indicates why the model successfully completed its response generation.
+
+- [`message_stop`](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types): Signals the end of the response.
+
+The following example shows the event sequence received when streaming a response:
+
+
+```json
+// 1. Message starts
+{"type":"message_start","message":{"model":"claude-sonnet-4-5-20250929","id":"msg_012zEkenyT6heaYSDvDEDdXm","type":"message","role":"assistant","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":12,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":0},"output_tokens":1,"service_tier":"standard"}}}
+
+// 2. Content block starts
+{"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
+
+// 3. Text tokens stream in as delta events
+{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Why"}}
+{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" don't scientists trust atoms?\n\nBecause"}}
+{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" they make up everything!"}}
+
+// 4. Content block completes
+{"type":"content_block_stop","index":0}
+
+// 5. Message delta (usage stats)
+{"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":12,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":17}}
+
+// 6. Message completes
+{"type":"message_stop"}
+```
+
+
+
+
+## Step 3: Publish streaming tokens to Ably
+
+Publish Anthropic streaming events to Ably using message appends to reliably and scalably distribute them to subscribers.
+
+Each AI response is stored as a single Ably message that grows as tokens are appended.
+
+### Initialize the Ably client
+
+Add the Ably client initialization to your `publisher.mjs` file:
+
+
+```javascript
+import Ably from 'ably';
+
+// Initialize Ably Realtime client
+const realtime = new Ably.Realtime({
+ key: '{{API_KEY}}',
+ echoMessages: false
+});
+
+// Create a channel for publishing streamed AI responses
+const channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}');
+```
+
+
+The Ably Realtime client maintains a persistent connection to the Ably service, which allows you to publish tokens at high message rates with low latency.
+
+
+
+### Publish initial message and append tokens
+
+When a new response begins, publish an initial message to create it. Ably assigns a [`serial`](/docs/messages#properties) identifier to the message. Use this `serial` to append each token to the message as it arrives from the Anthropic model.
+
+
+
+Update your `publisher.mjs` file to publish the initial message and append tokens:
+
+
+```javascript
+// Track state across events
+let msgSerial = null;
+let textBlockIndex = null;
+
+// Process each streaming event and publish to Ably
+async function processEvent(event) {
+ switch (event.type) {
+ case 'message_start':
+ // Publish initial empty message when response starts
+ const result = await channel.publish({
+ name: 'response',
+ data: ''
+ });
+
+ // Capture the message serial for appending tokens
+ msgSerial = result.serials[0];
+ break;
+
+ case 'content_block_start':
+ // Capture text block index when a text content block is added
+ if (event.content_block.type === 'text') {
+ textBlockIndex = event.index;
+ }
+ break;
+
+ case 'content_block_delta':
+ // Append tokens from text deltas only
+ if (event.index === textBlockIndex && event.delta.type === 'text_delta' && msgSerial) {
+ channel.appendMessage({
+ serial: msgSerial,
+ data: event.delta.text
+ });
+ }
+ break;
+
+ case 'message_stop':
+ console.log('Stream completed!');
+ break;
+ }
+}
+```
+
+
+This implementation:
+
+- Publishes an initial empty message when the response begins and captures the `serial`
+- Filters for `content_block_delta` events with `text_delta` type from text content blocks
+- Appends each token to the original message
+
+
+
+
+
+Run the publisher to see tokens streaming to Ably:
+
+
+```shell
+node publisher.mjs
+```
+
+
+## Step 4: Subscribe to streaming tokens
+
+Create a subscriber that receives the streaming tokens from Ably and reconstructs the response in realtime.
+
+Create a new file `subscriber.mjs` with the following contents:
+
+
+```javascript
+import Ably from 'ably';
+
+// Initialize Ably Realtime client
+const realtime = new Ably.Realtime({ key: '{{API_KEY}}' });
+
+// Get the same channel used by the publisher
+const channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}');
+
+// Track responses by message serial
+const responses = new Map();
+
+// Subscribe to receive messages
+await channel.subscribe((message) => {
+ switch (message.action) {
+ case 'message.create':
+ // New response started
+ console.log('\n[Response started]', message.serial);
+ responses.set(message.serial, message.data);
+ break;
+
+ case 'message.append':
+ // Append token to existing response
+ const current = responses.get(message.serial) || '';
+ responses.set(message.serial, current + message.data);
+
+ // Display token as it arrives
+ process.stdout.write(message.data);
+ break;
+
+ case 'message.update':
+ // Replace entire response content
+ responses.set(message.serial, message.data);
+ console.log('\n[Response updated with full content]');
+ break;
+ }
+});
+
+console.log('Subscriber ready, waiting for tokens...');
+```
+
+
+Subscribers receive different message actions depending on when they join and how they're retrieving messages:
+
+- `message.create`: Indicates a new response has started (i.e. a new message was created). The message `data` contains the initial content (often empty or the first token). Store this as the beginning of a new response using `serial` as the identifier.
+
+- `message.append`: Contains a single token fragment to append. The message `data` contains only the new token, not the full concatenated response. Append this token to the existing response identified by `serial`.
+
+- `message.update`: Contains the whole response up to that point. The message `data` contains the full concatenated text so far. Replace the entire response content with this data for the message identified by `serial`. This action occurs when the channel needs to resynchronize the full message state, such as after a client [resumes](/docs/connect/states#resume) from a transient disconnection.
+
+Run the subscriber in a separate terminal:
+
+
+```shell
+node subscriber.mjs
+```
+
+
+With the subscriber running, run the publisher in another terminal. The tokens stream in realtime as the Anthropic model generates them.
+
+## Step 5: Stream with multiple publishers and subscribers
+
+Ably's [channel-oriented sessions](/docs/ai-transport/sessions-identity#connection-oriented-vs-channel-oriented-sessions) enables multiple AI agents to publish responses and multiple users to receive them on a single channel simultaneously. Ably handles message delivery to all participants, eliminating the need to implement routing logic or manage state synchronization across connections.
+
+### Broadcasting to multiple subscribers
+
+Each subscriber receives the complete stream of tokens independently, enabling you to build collaborative experiences or multi-device applications.
+
+Run a subscriber in multiple separate terminals:
+
+
+```shell
+# Terminal 1
+node subscriber.mjs
+
+# Terminal 2
+node subscriber.mjs
+
+# Terminal 3
+node subscriber.mjs
+```
+
+
+All subscribers receive the same stream of tokens in realtime.
+
+### Publishing concurrent responses
+
+Multiple publishers can stream different responses concurrently on the same [channel](/docs/channels). Each response is a distinct message with its own unique `serial` identifier, so tokens from different responses are isolated to distinct messages and don't interfere with each other.
+
+To demonstrate this, run a publisher in multiple separate terminals:
+
+
+```shell
+# Terminal 1
+node publisher.mjs
+
+# Terminal 2
+node publisher.mjs
+
+# Terminal 3
+node publisher.mjs
+```
+
+
+All running subscribers receive tokens from all responses concurrently. Each subscriber correctly reconstructs each response separately using the `serial` to correlate tokens.
+
+## Step 6: Retrieve complete responses from history
+
+One key advantage of the message-per-response pattern is that each complete AI response is stored as a single message in channel history. This makes it efficient to retrieve conversation history without processing thousands of individual token messages.
+
+Use Ably's [rewind](/docs/channels/options/rewind) channel option to attach to the channel at some point in the recent past and automatically receive complete responses from history. Historical messages are delivered as `message.update` events containing the complete concatenated response, which then seamlessly transition to live `message.append` events for any ongoing responses:
+
+
+```javascript
+// Use rewind to receive recent historical messages
+const channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}', {
+ params: { rewind: '2m' } // Retrieve messages from the last 2 minutes
+});
+
+const responses = new Map();
+
+await channel.subscribe((message) => {
+ switch (message.action) {
+ case 'message.create':
+ responses.set(message.serial, message.data);
+ break;
+
+ case 'message.append':
+ const current = responses.get(message.serial) || '';
+ responses.set(message.serial, current + message.data);
+ process.stdout.write(message.data);
+ break;
+
+ case 'message.update':
+ // Historical messages contain full concatenated response
+ responses.set(message.serial, message.data);
+ console.log('\n[Historical response]:', message.data);
+ break;
+ }
+});
+```
+
+
+
+
+## Next steps
+
+- Learn more about the [message-per-response pattern](/docs/ai-transport/token-streaming/message-per-response) used in this guide
+- Learn about [client hydration strategies](/docs/ai-transport/token-streaming/message-per-response#hydration) for handling late joiners and reconnections
+- Understand [sessions and identity](/docs/ai-transport/sessions-identity) in AI enabled applications
+- Explore the [message-per-token pattern](/docs/ai-transport/token-streaming/message-per-token) for explicit control over individual token messages
diff --git a/src/pages/docs/guides/ai-transport/anthropic-message-per-token.mdx b/src/pages/docs/guides/ai-transport/anthropic-message-per-token.mdx
new file mode 100644
index 0000000000..996c3cb353
--- /dev/null
+++ b/src/pages/docs/guides/ai-transport/anthropic-message-per-token.mdx
@@ -0,0 +1,363 @@
+---
+title: "Guide: Stream Anthropic responses using the message-per-token pattern"
+meta_description: "Stream tokens from the Anthropic Messages API over Ably in realtime."
+meta_keywords: "AI, token streaming, Anthropic, Claude, Messages API, AI transport, Ably, realtime"
+---
+
+This guide shows you how to stream AI responses from Anthropic's [Messages API](https://docs.anthropic.com/en/api/messages) over Ably using the [message-per-token pattern](/docs/ai-transport/token-streaming/message-per-token). Specifically, it implements the [explicit start/stop events approach](/docs/ai-transport/token-streaming/message-per-token#explicit-events), which publishes each response token as an individual message, along with explicit lifecycle events to signal when responses begin and end.
+
+Using Ably to distribute tokens from the Anthropic SDK enables you to broadcast AI responses to thousands of concurrent subscribers with reliable message delivery and ordering guarantees, ensuring that each client receives the complete response stream with all tokens delivered in order. This approach decouples your AI inference from client connections, enabling you to scale agents independently and handle reconnections gracefully.
+
+
+
+## Prerequisites
+
+To follow this guide, you need:
+- Node.js 20 or higher
+- An Anthropic API key
+- An Ably API key
+
+Useful links:
+- [Anthropic API documentation](https://docs.anthropic.com/en/api)
+- [Ably JavaScript SDK getting started](/docs/getting-started/javascript)
+
+Create a new NPM package, which will contain the publisher and subscriber code:
+
+
+```shell
+mkdir ably-anthropic-example && cd ably-anthropic-example
+npm init -y
+```
+
+
+Install the required packages using NPM:
+
+
+```shell
+npm install @anthropic-ai/sdk@^0.71 ably@^2
+```
+
+
+
+
+Export your Anthropic API key to the environment, which will be used later in the guide by the Anthropic SDK:
+
+
+```shell
+export ANTHROPIC_API_KEY="your_api_key_here"
+```
+
+
+## Step 1: Get a streamed response from Anthropic
+
+Initialize an Anthropic client and use the [Messages API](https://docs.anthropic.com/en/api/messages) to stream model output as a series of events.
+
+Create a new file `publisher.mjs` with the following contents:
+
+
+```javascript
+import Anthropic from '@anthropic-ai/sdk';
+
+// Initialize Anthropic client
+const anthropic = new Anthropic();
+
+// Process each streaming event
+function processEvent(event) {
+ console.log(JSON.stringify(event));
+ // This function is updated in the next sections
+}
+
+// Create streaming response from Anthropic
+async function streamAnthropicResponse(prompt) {
+ const stream = await anthropic.messages.create({
+ model: "claude-sonnet-4-5",
+ max_tokens: 1024,
+ messages: [{ role: "user", content: prompt }],
+ stream: true,
+ });
+
+ // Iterate through streaming events
+ for await (const event of stream) {
+ processEvent(event);
+ }
+}
+
+// Usage example
+streamAnthropicResponse("Tell me a short joke");
+```
+
+
+### Understand Anthropic streaming events
+
+Anthropic's Messages API [streams](https://docs.anthropic.com/en/api/messages-streaming) model output as a series of events when you set `stream: true`. Each streamed event includes a `type` property which describes the event type. A complete text response can be constructed from the following event types:
+
+- [`message_start`](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types): Signals the start of a response. Contains a `message` object with an `id` to correlate subsequent events.
+
+- [`content_block_start`](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types): Indicates the start of a new content block. For text responses, the `content_block` will have `type: "text"`; other types may be specified, such as `"thinking"` for internal reasoning tokens. The `index` indicates the position of this item in the message's `content` array.
+
+- [`content_block_delta`](https://platform.claude.com/docs/en/build-with-claude/streaming#content-block-delta-types): Contains a single text delta in the `delta.text` field. If `delta.type === "text_delta"` the delta contains model response text; other types may be specified, such as `"thinking_delta"` for internal reasoning tokens. Use the `index` to correlate deltas relating to a specific content block.
+
+- [`content_block_stop`](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types): Signals completion of a content block. Contains the `index` that identifies content block.
+
+- [`message_delta`](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types): Contains additional message-level metadata that may be streamed incrementally. Includes a [`delta.stop_reason`](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons) which indicates why the model successfully completed its response generation.
+
+- [`message_stop`](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types): Signals the end of the response.
+
+The following example shows the event sequence received when streaming a response:
+
+
+```json
+// 1. Message starts
+{"type":"message_start","message":{"model":"claude-sonnet-4-5-20250929","id":"msg_016hhjrqVK4rCZ2uEGdyWfmt","type":"message","role":"assistant","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":12,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":0},"output_tokens":1,"service_tier":"standard"}}}
+
+// 2. Content block starts
+{"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
+
+// 3. Text tokens stream in as delta events
+{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Why"}}
+{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" don't scientists trust atoms?\n\nBecause"}}
+{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" they make up everything!"}}
+
+// 4. Content block completes
+{"type":"content_block_stop","index":0}
+
+// 5. Message delta (usage stats)
+{"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":12,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":17}}
+
+// 6. Message completes
+{"type":"message_stop"}
+```
+
+
+
+
+## Step 2: Publish streaming events to Ably
+
+Publish Anthropic streaming events to Ably to reliably and scalably distribute them to subscribers.
+
+This implementation follows the [explicit start/stop events pattern](/docs/ai-transport/token-streaming/message-per-token#explicit-events), which provides clear response boundaries.
+
+### Initialize the Ably client
+
+Add the Ably client initialization to your `publisher.mjs` file:
+
+
+```javascript
+import Ably from 'ably';
+
+// Initialize Ably Realtime client
+const realtime = new Ably.Realtime({
+ key: '{{API_KEY}}',
+ echoMessages: false
+});
+
+// Create a channel for publishing streamed AI responses
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+```
+
+
+The Ably Realtime client maintains a persistent connection to the Ably service, which allows you to publish tokens at high message rates with low latency.
+
+
+
+### Map Anthropic streaming events to Ably messages
+
+Choose how to map [Anthropic streaming events](#understand-streaming-events) to Ably [messages](/docs/messages). You can choose any mapping strategy that suits your application's needs. This guide uses the following pattern as an example:
+
+- `start`: Signals the beginning of a response
+- `token`: Contains the incremental text content for each delta
+- `stop`: Signals the completion of a response
+
+
+
+Update your `publisher.mjs` file to initialize the Ably client and update the `processEvent()` function to publish events to Ably:
+
+
+```javascript
+// Track state across events
+let responseId = null;
+
+// Process each streaming event and publish to Ably
+function processEvent(event) {
+ switch (event.type) {
+ case 'message_start':
+ // Capture message ID when response starts
+ responseId = event.message.id;
+
+ // Publish start event
+ channel.publish({
+ name: 'start',
+ extras: {
+ headers: { responseId }
+ }
+ });
+ break;
+
+ case 'content_block_delta':
+ // Publish tokens from text deltas only
+ if (event.delta.type === 'text_delta') {
+ channel.publish({
+ name: 'token',
+ data: event.delta.text,
+ extras: {
+ headers: { responseId }
+ }
+ });
+ }
+ break;
+
+ case 'message_stop':
+ // Publish stop event when response completes
+ channel.publish({
+ name: 'stop',
+ extras: {
+ headers: { responseId }
+ }
+ });
+ break;
+ }
+}
+```
+
+
+This implementation:
+
+- Publishes a `start` event when the response begins
+- Filters for `content_block_delta` events with `text_delta` type and publishes them as `token` events
+- Publishes a `stop` event when the response completes
+- All published events include the `responseId` in message [`extras`](/docs/messages#properties) to allow the client to correlate events relating to a particular response
+
+
+
+Run the publisher to see tokens streaming to Ably:
+
+
+```shell
+node publisher.mjs
+```
+
+
+## Step 3: Subscribe to streaming tokens
+
+Create a subscriber that receives the streaming events from Ably and reconstructs the response.
+
+Create a new file `subscriber.mjs` with the following contents:
+
+
+```javascript
+import Ably from 'ably';
+
+// Initialize Ably Realtime client
+const realtime = new Ably.Realtime({ key: '{{API_KEY}}' });
+
+// Get the same channel used by the publisher
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+// Track responses by ID
+const responses = new Map();
+
+// Handle response start
+await channel.subscribe('start', (message) => {
+ const responseId = message.extras?.headers?.responseId;
+ console.log('\n[Response started]', responseId);
+ responses.set(responseId, '');
+});
+
+// Handle tokens
+await channel.subscribe('token', (message) => {
+ const responseId = message.extras?.headers?.responseId;
+ const token = message.data;
+
+ // Append token to response
+ const currentText = responses.get(responseId) || '';
+ responses.set(responseId, currentText + token);
+
+ // Display token as it arrives
+ process.stdout.write(token);
+});
+
+// Handle response stop
+await channel.subscribe('stop', (message) => {
+ const responseId = message.extras?.headers?.responseId;
+ const finalText = responses.get(responseId);
+ console.log('\n[Response completed]', responseId);
+});
+
+console.log('Subscriber ready, waiting for tokens...');
+```
+
+
+Run the subscriber in a separate terminal:
+
+
+```shell
+node subscriber.mjs
+```
+
+
+With the subscriber running, run the publisher in another terminal. The tokens stream in realtime as the Anthropic model generates them.
+
+## Step 4: Stream with multiple publishers and subscribers
+
+Ably's [channel-oriented sessions](/docs/ai-transport/sessions-identity#connection-oriented-vs-channel-oriented-sessions) enables multiple AI agents to publish responses and multiple users to receive them on a single channel simultaneously. Ably handles message delivery to all participants, eliminating the need to implement routing logic or manage state synchronization across connections.
+
+### Broadcasting to multiple subscribers
+
+Each subscriber receives the complete stream of tokens independently, enabling you to build collaborative experiences or multi-device applications.
+
+Run a subscriber in multiple separate terminals:
+
+
+```shell
+# Terminal 1
+node subscriber.mjs
+
+# Terminal 2
+node subscriber.mjs
+
+# Terminal 3
+node subscriber.mjs
+```
+
+
+All subscribers receive the same stream of tokens in realtime.
+
+### Publishing concurrent responses
+
+The implementation uses `responseId` in message [`extras`](/docs/messages#properties) to correlate tokens with their originating response. This enables multiple publishers to stream different responses concurrently on the same [channel](/docs/channels), with each subscriber correctly tracking all responses independently.
+
+To demonstrate this, run a publisher in multiple separate terminals:
+
+
+```shell
+# Terminal 1
+node publisher.mjs
+
+# Terminal 2
+node publisher.mjs
+
+# Terminal 3
+node publisher.mjs
+```
+
+
+All running subscribers receive tokens from all responses concurrently. Each subscriber correctly reconstructs each response separately using the `responseId` to correlate tokens.
+
+## Next steps
+
+- Learn more about the [message-per-token pattern](/docs/ai-transport/token-streaming/message-per-token) used in this guide
+- Learn about [client hydration strategies](/docs/ai-transport/token-streaming/message-per-token#hydration) for handling late joiners and reconnections
+- Understand [sessions and identity](/docs/ai-transport/sessions-identity) in AI enabled applications
+- Explore the [message-per-response pattern](/docs/ai-transport/token-streaming/message-per-response) for storing complete AI responses as single messages in history
diff --git a/src/pages/docs/guides/ai-transport/openai-message-per-response.mdx b/src/pages/docs/guides/ai-transport/openai-message-per-response.mdx
new file mode 100644
index 0000000000..0aeb1ac49a
--- /dev/null
+++ b/src/pages/docs/guides/ai-transport/openai-message-per-response.mdx
@@ -0,0 +1,444 @@
+---
+title: "Guide: Stream OpenAI responses using the message-per-response pattern"
+meta_description: "Stream tokens from the OpenAI Responses API over Ably in realtime using message appends."
+meta_keywords: "AI, token streaming, OpenAI, Responses API, AI transport, Ably, realtime, message appends"
+---
+
+This guide shows you how to stream AI responses from OpenAI's [Responses API](https://platform.openai.com/docs/api-reference/responses) over Ably using the [message-per-response pattern](/docs/ai-transport/token-streaming/message-per-response). Specifically, it appends each response token to a single Ably message, creating a complete AI response that grows incrementally while delivering tokens in realtime.
+
+Using Ably to distribute tokens from the OpenAI SDK enables you to broadcast AI responses to thousands of concurrent subscribers with reliable message delivery and ordering guarantees. This approach stores each complete response as a single message in channel history, making it easy to retrieve conversation history without processing thousands of individual token messages.
+
+
+
+## Prerequisites
+
+To follow this guide, you need:
+- Node.js 20 or higher
+- An OpenAI API key
+- An Ably API key
+
+Useful links:
+- [OpenAI developer quickstart](https://platform.openai.com/docs/quickstart)
+- [Ably JavaScript SDK getting started](/docs/getting-started/javascript)
+
+Create a new NPM package, which will contain the publisher and subscriber code:
+
+
+```shell
+mkdir ably-openai-example && cd ably-openai-example
+npm init -y
+```
+
+
+Install the required packages using NPM:
+
+
+```shell
+npm install openai@^4 ably@^2
+```
+
+
+
+
+Export your OpenAI API key to the environment, which will be used later in the guide by the OpenAI SDK:
+
+
+```shell
+export OPENAI_API_KEY="your_api_key_here"
+```
+
+
+## Step 1: Enable message appends
+
+Message append functionality requires "Message annotations, updates, deletes and appends" to be enabled in a [channel rule](/docs/channels#rules) associated with the channel.
+
+
+
+To enable the channel rule:
+
+1. Go to the [Ably dashboard](https://www.ably.com/dashboard) and select your app.
+2. Navigate to the "Configuration" > "Rules" section from the left-hand navigation bar.
+3. Choose "Add new rule".
+4. Enter a channel name or namespace pattern (e.g. `ai` for all channels starting with `ai:`).
+5. Select the "Message annotations, updates, deletes and appends" option from the list.
+6. Click "Create channel rule".
+
+The examples in this guide use the `ai:` namespace prefix, which assumes you have configured the rule for `ai:*`.
+
+
+
+## Step 2: Get a streamed response from OpenAI
+
+Initialize an OpenAI client and use the [Responses API](https://platform.openai.com/docs/api-reference/responses) to stream model output as a series of events.
+
+Create a new file `publisher.mjs` with the following contents:
+
+
+```javascript
+import OpenAI from 'openai';
+
+// Initialize OpenAI client
+const openai = new OpenAI();
+
+// Process each streaming event
+async function processEvent(event) {
+ console.log(JSON.stringify(event));
+ // This function is updated in the next sections
+}
+
+// Create streaming response from OpenAI
+async function streamOpenAIResponse(prompt) {
+ const stream = await openai.responses.create({
+ model: "gpt-5",
+ input: prompt,
+ stream: true,
+ });
+
+ // Iterate through streaming events
+ for await (const event of stream) {
+ await processEvent(event);
+ }
+}
+
+// Usage example
+streamOpenAIResponse("Tell me a short joke");
+```
+
+
+### Understand OpenAI streaming events
+
+OpenAI's Responses API [streams](https://platform.openai.com/docs/guides/streaming-responses) model output as a series of events when you set `stream: true`. Each streamed event includes a `type` property which describes the [event type](https://platform.openai.com/docs/api-reference/responses-streaming). A complete text response can be constructed from the following event types:
+
+- [`response.created`](https://platform.openai.com/docs/api-reference/responses-streaming/response/created): Signals the start of a response. Contains `response.id` to correlate subsequent events.
+
+- [`response.output_item.added`](https://platform.openai.com/docs/api-reference/responses-streaming/response/output_item/added): Indicates a new output item. If `item.type === "message"` the item contains model response text; other types may be specified, such as `"reasoning"` for internal reasoning tokens. The `output_index` indicates the position of this item in the response's [`output`](https://platform.openai.com/docs/api-reference/responses-streaming/response/completed#responses_streaming-response-completed-response-output) array.
+
+- [`response.content_part.added`](https://platform.openai.com/docs/api-reference/responses-streaming/response/content_part/added): Indicates a new content part within an output item. If `part.type === "output_text"` the part contains model response text; other types may be specified, such as `"reasoning_text"` for internal reasoning tokens. The `content_index` indicates the position of this item in the output items's [`content`](https://platform.openai.com/docs/api-reference/responses-streaming/response/completed#responses_streaming-response-completed-response-output-output_message-content) array.
+
+- [`response.output_text.delta`](https://platform.openai.com/docs/api-reference/responses-streaming/response/output_text/delta): Contains a single token in the `delta` field. Use the `item_id`, `output_index`, and `content_index` to correlate tokens relating to a specific content part.
+
+- [`response.content_part.done`](https://platform.openai.com/docs/api-reference/responses-streaming/response/content_part/done): Signals completion of a content part. Contains the complete `part` object with full text, along with `item_id`, `output_index`, and `content_index`.
+
+- [`response.output_item.done`](https://platform.openai.com/docs/api-reference/responses-streaming/response/output_item/done): Signals completion of an output item. Contains the complete `item` object and `output_index`.
+
+- [`response.completed`](https://platform.openai.com/docs/api-reference/responses-streaming/response/completed): Signals the end of the response. Contains the complete `response` object.
+
+The following example shows the event sequence received when streaming a response:
+
+
+```json
+// 1. Response starts
+{"type":"response.created","response":{"id":"resp_abc123","status":"in_progress"}}
+
+// 2. First output item (reasoning) is added
+{"type":"response.output_item.added","output_index":0,"item":{"id":"rs_456","type":"reasoning"}}
+{"type":"response.output_item.done","output_index":0,"item":{"id":"rs_456","type":"reasoning"}}
+
+// 3. Second output item (message) is added
+{"type":"response.output_item.added","output_index":1,"item":{"id":"msg_789","type":"message"}}
+{"type":"response.content_part.added","item_id":"msg_789","output_index":1,"content_index":0}
+
+// 4. Text tokens stream in as delta events
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":"Why"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":" don"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":"'t"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":" scientists"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":" trust"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":" atoms"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":"?"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":" Because"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":" they"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":" make"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":" up"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":" everything"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":"."}
+
+// 5. Content part and output item complete
+{"type":"response.content_part.done","item_id":"msg_789","output_index":1,"content_index":0,"part":{"type":"output_text","text":"Why don't scientists trust atoms? Because they make up everything."}}
+{"type":"response.output_item.done","output_index":1,"item":{"id":"msg_789","type":"message","status":"completed","content":[{"type":"output_text","text":"Why don't scientists trust atoms? Because they make up everything."}]}}
+
+// 6. Response completes
+{"type":"response.completed","response":{"id":"resp_abc123","status":"completed","output":[{"id":"rs_456","type":"reasoning"},{"id":"msg_789","type":"message","status":"completed","content":[{"type":"output_text","text":"Why don't scientists trust atoms? Because they make up everything."}]}]}}
+```
+
+
+
+
+## Step 3: Publish streaming tokens to Ably
+
+Publish OpenAI streaming events to Ably using message appends to reliably and scalably distribute them to subscribers.
+
+Each AI response is stored as a single Ably message that grows as tokens are appended.
+
+### Initialize the Ably client
+
+Add the Ably client initialization to your `publisher.mjs` file:
+
+
+```javascript
+import Ably from 'ably';
+
+// Initialize Ably Realtime client
+const realtime = new Ably.Realtime({
+ key: '{{API_KEY}}',
+ echoMessages: false
+});
+
+// Create a channel for publishing streamed AI responses
+const channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}');
+```
+
+
+The Ably Realtime client maintains a persistent connection to the Ably service, which allows you to publish tokens at high message rates with low latency.
+
+
+
+### Publish initial message and append tokens
+
+When a new response begins, publish an initial message to create it. Ably assigns a [`serial`](/docs/messages#properties) identifier to the message. Use this `serial` to append each token to the message as it arrives from the OpenAI model.
+
+
+
+Update your `publisher.mjs` file to publish the initial message and append tokens:
+
+
+```javascript
+// Track state across events
+let msgSerial = null;
+let messageItemId = null;
+
+// Process each streaming event and publish to Ably
+async function processEvent(event) {
+ switch (event.type) {
+ case 'response.created':
+ // Publish initial empty message when response starts
+ const result = await channel.publish({
+ name: 'response',
+ data: ''
+ });
+
+ // Capture the message serial for appending tokens
+ msgSerial = result.serials[0];
+ break;
+
+ case 'response.output_item.added':
+ // Capture message item ID when a message output item is added
+ if (event.item.type === 'message') {
+ messageItemId = event.item.id;
+ }
+ break;
+
+ case 'response.output_text.delta':
+ // Append tokens from message output items only
+ if (event.item_id === messageItemId && msgSerial) {
+ channel.appendMessage({
+ serial: msgSerial,
+ data: event.delta
+ });
+ }
+ break;
+
+ case 'response.completed':
+ console.log('Stream completed!');
+ break;
+ }
+}
+```
+
+
+This implementation:
+
+- Publishes an initial empty message when the response begins and captures the `serial`
+- Filters for `response.output_text.delta` events from `message` type output items
+- Appends each token to the original message
+
+
+
+
+
+Run the publisher to see tokens streaming to Ably:
+
+
+```shell
+node publisher.mjs
+```
+
+
+## Step 4: Subscribe to streaming tokens
+
+Create a subscriber that receives the streaming tokens from Ably and reconstructs the response in realtime.
+
+Create a new file `subscriber.mjs` with the following contents:
+
+
+```javascript
+import Ably from 'ably';
+
+// Initialize Ably Realtime client
+const realtime = new Ably.Realtime({ key: '{{API_KEY}}' });
+
+// Get the same channel used by the publisher
+const channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}');
+
+// Track responses by message serial
+const responses = new Map();
+
+// Subscribe to receive messages
+await channel.subscribe((message) => {
+ switch (message.action) {
+ case 'message.create':
+ // New response started
+ console.log('\n[Response started]', message.serial);
+ responses.set(message.serial, message.data);
+ break;
+
+ case 'message.append':
+ // Append token to existing response
+ const current = responses.get(message.serial) || '';
+ responses.set(message.serial, current + message.data);
+
+ // Display token as it arrives
+ process.stdout.write(message.data);
+ break;
+
+ case 'message.update':
+ // Replace entire response content
+ responses.set(message.serial, message.data);
+ console.log('\n[Response updated with full content]');
+ break;
+ }
+});
+
+console.log('Subscriber ready, waiting for tokens...');
+```
+
+
+Subscribers receive different message actions depending on when they join and how they're retrieving messages:
+
+- `message.create`: Indicates a new response has started (i.e. a new message was created). The message `data` contains the initial content (often empty or the first token). Store this as the beginning of a new response using `serial` as the identifier.
+
+- `message.append`: Contains a single token fragment to append. The message `data` contains only the new token, not the full concatenated response. Append this token to the existing response identified by `serial`.
+
+- `message.update`: Contains the whole response up to that point. The message `data` contains the full concatenated text so far. Replace the entire response content with this data for the message identified by `serial`. This action occurs when the channel needs to resynchronize the full message state, such as after a client [resumes](/docs/connect/states#resume) from a transient disconnection.
+
+Run the subscriber in a separate terminal:
+
+
+```shell
+node subscriber.mjs
+```
+
+
+With the subscriber running, run the publisher in another terminal. The tokens stream in realtime as the OpenAI model generates them.
+
+## Step 5: Stream with multiple publishers and subscribers
+
+Ably's [channel-oriented sessions](/docs/ai-transport/sessions-identity#connection-oriented-vs-channel-oriented-sessions) enables multiple AI agents to publish responses and multiple users to receive them on a single channel simultaneously. Ably handles message delivery to all participants, eliminating the need to implement routing logic or manage state synchronization across connections.
+
+### Broadcasting to multiple subscribers
+
+Each subscriber receives the complete stream of tokens independently, enabling you to build collaborative experiences or multi-device applications.
+
+Run a subscriber in multiple separate terminals:
+
+
+```shell
+# Terminal 1
+node subscriber.mjs
+
+# Terminal 2
+node subscriber.mjs
+
+# Terminal 3
+node subscriber.mjs
+```
+
+
+All subscribers receive the same stream of tokens in realtime.
+
+### Publishing concurrent responses
+
+Multiple publishers can stream different responses concurrently on the same [channel](/docs/channels). Each response is a distinct message with its own unique `serial` identifier, so tokens from different responses are isolated to distinct messages and don't interfere with each other.
+
+To demonstrate this, run a publisher in multiple separate terminals:
+
+
+```shell
+# Terminal 1
+node publisher.mjs
+
+# Terminal 2
+node publisher.mjs
+
+# Terminal 3
+node publisher.mjs
+```
+
+
+All running subscribers receive tokens from all responses concurrently. Each subscriber correctly reconstructs each response separately using the `serial` to correlate tokens.
+
+## Step 6: Retrieve complete responses from history
+
+One key advantage of the message-per-response pattern is that each complete AI response is stored as a single message in channel history. This makes it efficient to retrieve conversation history without processing thousands of individual token messages.
+
+Use Ably's [rewind](/docs/channels/options/rewind) channel option to attach to the channel at some point in the recent past and automatically receive complete responses from history. Historical messages are delivered as `message.update` events containing the complete concatenated response, which then seamlessly transition to live `message.append` events for any ongoing responses:
+
+
+```javascript
+// Use rewind to receive recent historical messages
+const channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}', {
+ params: { rewind: '2m' } // Retrieve messages from the last 2 minutes
+});
+
+const responses = new Map();
+
+await channel.subscribe((message) => {
+ switch (message.action) {
+ case 'message.create':
+ responses.set(message.serial, message.data);
+ break;
+
+ case 'message.append':
+ const current = responses.get(message.serial) || '';
+ responses.set(message.serial, current + message.data);
+ process.stdout.write(message.data);
+ break;
+
+ case 'message.update':
+ // Historical messages contain full concatenated response
+ responses.set(message.serial, message.data);
+ console.log('\n[Historical response]:', message.data);
+ break;
+ }
+});
+```
+
+
+
+
+## Next steps
+
+- Learn more about the [message-per-response pattern](/docs/ai-transport/token-streaming/message-per-response) used in this guide
+- Learn about [client hydration strategies](/docs/ai-transport/token-streaming/message-per-response#hydration) for handling late joiners and reconnections
+- Understand [sessions and identity](/docs/ai-transport/sessions-identity) in AI enabled applications
+- Explore the [message-per-token pattern](/docs/ai-transport/token-streaming/message-per-token) for explicit control over individual token messages
diff --git a/src/pages/docs/guides/ai-transport/openai-message-per-token.mdx b/src/pages/docs/guides/ai-transport/openai-message-per-token.mdx
new file mode 100644
index 0000000000..e2a0d84717
--- /dev/null
+++ b/src/pages/docs/guides/ai-transport/openai-message-per-token.mdx
@@ -0,0 +1,385 @@
+---
+title: "Guide: Stream OpenAI responses using the message-per-token pattern"
+meta_description: "Stream tokens from the OpenAI Responses API over Ably in realtime."
+meta_keywords: "AI, token streaming, OpenAI, Responses API, AI transport, Ably, realtime"
+---
+
+This guide shows you how to stream AI responses from OpenAI's [Responses API](https://platform.openai.com/docs/api-reference/responses) over Ably using the [message-per-token pattern](/docs/ai-transport/token-streaming/message-per-token). Specifically, it implements the [explicit start/stop events approach](/docs/ai-transport/token-streaming/message-per-token#explicit-events), which publishes each response token as an individual message, along with explicit lifecycle events to signal when responses begin and end.
+
+Using Ably to distribute tokens from the OpenAI SDK enables you to broadcast AI responses to thousands of concurrent subscribers with reliable message delivery and ordering guarantees, ensuring that each client receives the complete response stream with all tokens delivered in order. This approach decouples your AI inference from client connections, enabling you to scale agents independently and handle reconnections gracefully.
+
+
+
+## Prerequisites
+
+To follow this guide, you need:
+- Node.js 20 or higher
+- An OpenAI API key
+- An Ably API key
+
+Useful links:
+- [OpenAI developer quickstart](https://platform.openai.com/docs/quickstart)
+- [Ably JavaScript SDK getting started](/docs/getting-started/javascript)
+
+Create a new NPM package, which will contain the publisher and subscriber code:
+
+
+```shell
+mkdir ably-openai-example && cd ably-openai-example
+npm init -y
+```
+
+
+Install the required packages using NPM:
+
+
+```shell
+npm install openai@^4 ably@^2
+```
+
+
+
+
+Export your OpenAI API key to the environment, which will be used later in the guide by the OpenAI SDK:
+
+
+```shell
+export OPENAI_API_KEY="your_api_key_here"
+```
+
+
+## Step 1: Get a streamed response from OpenAI
+
+Initialize an OpenAI client and use the [Responses API](https://platform.openai.com/docs/api-reference/responses) to stream model output as a series of events.
+
+Create a new file `publisher.mjs` with the following contents:
+
+
+```javascript
+import OpenAI from 'openai';
+
+// Initialize OpenAI client
+const openai = new OpenAI();
+
+// Process each streaming event
+function processEvent(event) {
+ console.log(JSON.stringify(event));
+ // This function is updated in the next sections
+}
+
+// Create streaming response from OpenAI
+async function streamOpenAIResponse(prompt) {
+ const stream = await openai.responses.create({
+ model: "gpt-5",
+ input: prompt,
+ stream: true,
+ });
+
+ // Iterate through streaming events
+ for await (const event of stream) {
+ processEvent(event);
+ }
+}
+
+// Usage example
+streamOpenAIResponse("Tell me a short joke");
+```
+
+
+### Understand OpenAI streaming events
+
+OpenAI's Responses API [streams](https://platform.openai.com/docs/guides/streaming-responses) model output as a series of events when you set `stream: true`. Each streamed event includes a `type` property which describes the [event type](https://platform.openai.com/docs/api-reference/responses-streaming). A complete text response can be constructed from the following event types:
+
+- [`response.created`](https://platform.openai.com/docs/api-reference/responses-streaming/response/created): Signals the start of a response. Contains `response.id` to correlate subsequent events.
+
+- [`response.output_item.added`](https://platform.openai.com/docs/api-reference/responses-streaming/response/output_item/added): Indicates a new output item. If `item.type === "message"` the item contains model response text; other types may be specified, such as `"reasoning"` for internal reasoning tokens. The `output_index` indicates the position of this item in the response's [`output`](https://platform.openai.com/docs/api-reference/responses-streaming/response/completed#responses_streaming-response-completed-response-output) array.
+
+- [`response.content_part.added`](https://platform.openai.com/docs/api-reference/responses-streaming/response/content_part/added): Indicates a new content part within an output item. If `part.type === "output_text"` the part contains model response text; other types may be specified, such as `"reasoning_text"` for internal reasoning tokens. The `content_index` indicates the position of this item in the output items's [`content`](https://platform.openai.com/docs/api-reference/responses-streaming/response/completed#responses_streaming-response-completed-response-output-output_message-content) array.
+
+- [`response.output_text.delta`](https://platform.openai.com/docs/api-reference/responses-streaming/response/output_text/delta): Contains a single token in the `delta` field. Use the `item_id`, `output_index`, and `content_index` to correlate tokens relating to a specific content part.
+
+- [`response.content_part.done`](https://platform.openai.com/docs/api-reference/responses-streaming/response/content_part/done): Signals completion of a content part. Contains the complete `part` object with full text, along with `item_id`, `output_index`, and `content_index`.
+
+- [`response.output_item.done`](https://platform.openai.com/docs/api-reference/responses-streaming/response/output_item/done): Signals completion of an output item. Contains the complete `item` object and `output_index`.
+
+- [`response.completed`](https://platform.openai.com/docs/api-reference/responses-streaming/response/completed): Signals the end of the response. Contains the complete `response` object.
+
+The following example shows the event sequence received when streaming a response:
+
+
+```json
+// 1. Response starts
+{"type":"response.created","response":{"id":"resp_abc123","status":"in_progress"}}
+
+// 2. First output item (reasoning) is added
+{"type":"response.output_item.added","output_index":0,"item":{"id":"rs_456","type":"reasoning"}}
+{"type":"response.output_item.done","output_index":0,"item":{"id":"rs_456","type":"reasoning"}}
+
+// 3. Second output item (message) is added
+{"type":"response.output_item.added","output_index":1,"item":{"id":"msg_789","type":"message"}}
+{"type":"response.content_part.added","item_id":"msg_789","output_index":1,"content_index":0}
+
+// 4. Text tokens stream in as delta events
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":"Why"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":" don"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":"'t"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":" scientists"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":" trust"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":" atoms"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":"?"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":" Because"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":" they"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":" make"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":" up"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":" everything"}
+{"type":"response.output_text.delta","item_id":"msg_789","output_index":1,"content_index":0,"delta":"."}
+
+// 5. Content part and output item complete
+{"type":"response.content_part.done","item_id":"msg_789","output_index":1,"content_index":0,"part":{"type":"output_text","text":"Why don't scientists trust atoms? Because they make up everything."}}
+{"type":"response.output_item.done","output_index":1,"item":{"id":"msg_789","type":"message","status":"completed","content":[{"type":"output_text","text":"Why don't scientists trust atoms? Because they make up everything."}]}}
+
+// 6. Response completes
+{"type":"response.completed","response":{"id":"resp_abc123","status":"completed","output":[{"id":"rs_456","type":"reasoning"},{"id":"msg_789","type":"message","status":"completed","content":[{"type":"output_text","text":"Why don't scientists trust atoms? Because they make up everything."}]}]}}
+```
+
+
+
+
+## Step 2: Publish streaming events to Ably
+
+Publish OpenAI streaming events to Ably to reliably and scalably distribute them to subscribers.
+
+This implementation follows the [explicit start/stop events pattern](/docs/ai-transport/token-streaming/message-per-token#explicit-events), which provides clear response boundaries.
+
+### Initialize the Ably client
+
+Add the Ably client initialization to your `publisher.mjs` file:
+
+
+```javascript
+import Ably from 'ably';
+
+// Initialize Ably Realtime client
+const realtime = new Ably.Realtime({
+ key: '{{API_KEY}}',
+ echoMessages: false
+});
+
+// Create a channel for publishing streamed AI responses
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+```
+
+
+The Ably Realtime client maintains a persistent connection to the Ably service, which allows you to publish tokens at high message rates with low latency.
+
+
+
+### Map OpenAI streaming events to Ably messages
+
+Choose how to map [OpenAI streaming events](#understand-streaming-events) to Ably [messages](/docs/messages). You can choose any mapping strategy that suits your application's needs. This guide uses the following pattern as an example:
+
+- `start`: Signals the beginning of a response
+- `token`: Contains the incremental text content for each delta
+- `stop`: Signals the completion of a response
+
+
+
+Update your `publisher.mjs` file to initialize the Ably client and update the `processEvent()` function to publish events to Ably:
+
+
+```javascript
+// Track state across events
+let responseId = null;
+let messageItemId = null;
+
+// Process each streaming event and publish to Ably
+function processEvent(event) {
+ switch (event.type) {
+ case 'response.created':
+ // Capture response ID when response starts
+ responseId = event.response.id;
+
+ // Publish start event
+ channel.publish({
+ name: 'start',
+ extras: {
+ headers: { responseId }
+ }
+ });
+ break;
+
+ case 'response.output_item.added':
+ // Capture message item ID when a message output item is added
+ if (event.item.type === 'message') {
+ messageItemId = event.item.id;
+ }
+ break;
+
+ case 'response.output_text.delta':
+ // Publish tokens from message output items only
+ if (event.item_id === messageItemId) {
+ channel.publish({
+ name: 'token',
+ data: event.delta,
+ extras: {
+ headers: { responseId }
+ }
+ });
+ }
+ break;
+
+ case 'response.completed':
+ // Publish stop event when response completes
+ channel.publish({
+ name: 'stop',
+ extras: {
+ headers: { responseId }
+ }
+ });
+ break;
+ }
+}
+```
+
+
+This implementation:
+
+- Publishes a `start` event when the response begins
+- Filters for `response.output_text.delta` events from `message` type output items and publishes them as `token` events
+- Publishes a `stop` event when the response completes
+- All published events include the `responseId` in message [`extras`](/docs/messages#properties) to allow the client to correlate events relating to a particular response
+
+
+
+Run the publisher to see tokens streaming to Ably:
+
+
+```shell
+node publisher.mjs
+```
+
+
+## Step 3: Subscribe to streaming tokens
+
+Create a subscriber that receives the streaming events from Ably and reconstructs the response.
+
+Create a new file `subscriber.mjs` with the following contents:
+
+
+```javascript
+import Ably from 'ably';
+
+// Initialize Ably Realtime client
+const realtime = new Ably.Realtime({ key: '{{API_KEY}}' });
+
+// Get the same channel used by the publisher
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+// Track responses by ID
+const responses = new Map();
+
+// Handle response start
+await channel.subscribe('start', (message) => {
+ const responseId = message.extras?.headers?.responseId;
+ console.log('\n[Response started]', responseId);
+ responses.set(responseId, '');
+});
+
+// Handle tokens
+await channel.subscribe('token', (message) => {
+ const responseId = message.extras?.headers?.responseId;
+ const token = message.data;
+
+ // Append token to response
+ const currentText = responses.get(responseId) || '';
+ responses.set(responseId, currentText + token);
+
+ // Display token as it arrives
+ process.stdout.write(token);
+});
+
+// Handle response stop
+await channel.subscribe('stop', (message) => {
+ const responseId = message.extras?.headers?.responseId;
+ const finalText = responses.get(responseId);
+ console.log('\n[Response completed]', responseId);
+});
+
+console.log('Subscriber ready, waiting for tokens...');
+```
+
+
+Run the subscriber in a separate terminal:
+
+
+```shell
+node subscriber.mjs
+```
+
+
+With the subscriber running, run the publisher in another terminal. The tokens stream in realtime as the OpenAI model generates them.
+
+## Step 4: Stream with multiple publishers and subscribers
+
+Ably's [channel-oriented sessions](/docs/ai-transport/sessions-identity#connection-oriented-vs-channel-oriented-sessions) enables multiple AI agents to publish responses and multiple users to receive them on a single channel simultaneously. Ably handles message delivery to all participants, eliminating the need to implement routing logic or manage state synchronization across connections.
+
+### Broadcasting to multiple subscribers
+
+Each subscriber receives the complete stream of tokens independently, enabling you to build collaborative experiences or multi-device applications.
+
+Run a subscriber in multiple separate terminals:
+
+
+```shell
+# Terminal 1
+node subscriber.mjs
+
+# Terminal 2
+node subscriber.mjs
+
+# Terminal 3
+node subscriber.mjs
+```
+
+
+All subscribers receive the same stream of tokens in realtime.
+
+### Publishing concurrent responses
+
+The implementation uses `responseId` in message [`extras`](/docs/messages#properties) to correlate tokens with their originating response. This enables multiple publishers to stream different responses concurrently on the same [channel](/docs/channels), with each subscriber correctly tracking all responses independently.
+
+To demonstrate this, run a publisher in multiple separate terminals:
+
+
+```shell
+# Terminal 1
+node publisher.mjs
+
+# Terminal 2
+node publisher.mjs
+
+# Terminal 3
+node publisher.mjs
+```
+
+
+All running subscribers receive tokens from all responses concurrently. Each subscriber correctly reconstructs each response separately using the `responseId` to correlate tokens.
+
+## Next steps
+
+- Learn more about the [message-per-token pattern](/docs/ai-transport/token-streaming/message-per-token) used in this guide
+- Learn about [client hydration strategies](/docs/ai-transport/token-streaming/message-per-token#hydration) for handling late joiners and reconnections
+- Understand [sessions and identity](/docs/ai-transport/sessions-identity) in AI enabled applications
+- Explore the [message-per-response pattern](/docs/ai-transport/token-streaming/message-per-response) for storing complete AI responses as single messages in history
diff --git a/src/pages/docs/messages/annotations.mdx b/src/pages/docs/messages/annotations.mdx
index 4eafc6dd87..1d050f3a0a 100644
--- a/src/pages/docs/messages/annotations.mdx
+++ b/src/pages/docs/messages/annotations.mdx
@@ -19,18 +19,18 @@ When clients publish or delete an annotation, Ably automatically creates a [summ
## Enable annotations
-Annotations can be enabled for a channel or channel namespace with the *Message annotations, updates, and deletes* channel rule.
+Annotations can be enabled for a channel or channel namespace with the *Message annotations, updates, deletes, and appends* channel rule.
1. Go to the **Settings** tab of an app in your dashboard.
3. Under [channel rules](/docs/channels#rules), click **Add new rule**.
4. Enter the channel name or channel namespace on which to enable message annotations.
-5. Check **Message annotations, updates, and deletes** to enable message annotations.
+5. Check **Message annotations, updates, deletes, and appends** to enable message annotations.
6. Click **Create channel rule** to save.
## Annotation types
diff --git a/src/pages/docs/messages/index.mdx b/src/pages/docs/messages/index.mdx
index d3ecbad18a..f148ff6eee 100644
--- a/src/pages/docs/messages/index.mdx
+++ b/src/pages/docs/messages/index.mdx
@@ -34,7 +34,7 @@ The following are the properties of a message:
| **extras** | A JSON object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads. Valid payloads include those related to [Push Notifications](/docs/push), [deltas](/docs/channels/options/deltas) and headers |
| **encoding** | This is typically empty, as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute contains the remaining transformations not applied to the data payload |
| **action** | An [enum](/docs/api/realtime-sdk/types#message-action) telling you whether this is a normal ('create') message, an update to a previous message, an annotation summary, etc. |
-| **serial** | The message's serial (a server-assigned identifier that will be the same in all future updates of this message, and can be used to add [annotations](/docs/messages/annotations) or to [update or delete](/docs/messages/updates-deletes) the message). This will only be set if you enable annotations, updates, and deletes in [channel rules](/docs/channels#rules) |
+| **serial** | The message's serial (a server-assigned identifier that will be the same in all future updates of this message, and can be used to add [annotations](/docs/messages/annotations) or to [update or delete](/docs/messages/updates-deletes) the message). This will only be set if you enable annotations, updates, deletes, and appends in [channel rules](/docs/channels#rules) |
| **annotations** | An object containing a summary of any [annotations](/docs/messages/annotations) that have been made to the message |
| **version** | An object containing [version metadata](/docs/messages/updates-deletes#version-structure) for messages that have been updated or deleted |
diff --git a/src/pages/docs/messages/updates-deletes.mdx b/src/pages/docs/messages/updates-deletes.mdx
index 917e92382a..e557e64032 100644
--- a/src/pages/docs/messages/updates-deletes.mdx
+++ b/src/pages/docs/messages/updates-deletes.mdx
@@ -23,18 +23,18 @@ You can access the full version history of any given message.
## Enable message updates and deletes
-Message updates and deletes can be enabled for a channel or channel namespace with the *Message annotations, updates, and deletes* channel rule.
+Message updates and deletes can be enabled for a channel or channel namespace with the *Message annotations, updates, deletes, and appends* channel rule.
1. Go to the **Settings** tab of an app in your dashboard.
2. Under [channel rules](/docs/channels#rules), click **Add new rule**.
3. Enter the channel name or channel namespace on which to enable message updates and deletes.
-4. Check **Message annotations, updates, and deletes** to enable the feature.
+4. Check **Message annotations, updates, deletes, and appends** to enable the feature.
5. Click **Create channel rule** to save.
## Update a message
diff --git a/src/pages/docs/platform/errors/codes.mdx b/src/pages/docs/platform/errors/codes.mdx
index 538ae2279e..0e6eb53a13 100644
--- a/src/pages/docs/platform/errors/codes.mdx
+++ b/src/pages/docs/platform/errors/codes.mdx
@@ -149,7 +149,7 @@ Resolution: The following steps can help resolve this issue:
This error occurs when the requested operation is only available in a newer version of the Ably protocol than the one specified in the request. This can happen if the client is using an older version of the Ably SDK that does not support the requested operation.
-Examples of this error include attempting to use [channel objects](/docs/liveobjects) or message annotations, updates and deletes from an Ably SDK that does not support protocol version 2.
+Examples of this error include attempting to use [channel objects](/docs/liveobjects) or message annotations, updates, deletes, and appends from an Ably SDK that does not support protocol version 2.
Resolution: The following steps can help resolve this issue:
* Upgrade the Ably SDK to a version that supports the requested operation.
@@ -773,12 +773,12 @@ This error occurs when attempting to [subscribe to individual annotations](/docs
**Resolution:**
* Ensure that `annotation_subscribe` mode is specified in the client [channel options](/docs/channels/options) before subscribing to individual annotations.
-## 93002: Annotations are only supported on channels with message annotations, updates, and deletes enabled
+## 93002: Annotations are only supported on channels with message annotations, updates, deletes, and appends enabled
This error occurs when attempting to use [message annotations](/docs/messages/annotations) on a channel that does not have them enabled.
**Resolution:**
-* Create a [channel rule](/docs/channels#rules) for the channel or channel namespace with **Message annotations, updates, and deletes** enabled.
+* Create a [channel rule](/docs/channels#rules) for the channel or channel namespace with **Message annotations, updates, deletes, and appends** enabled.
## 101000: Space name missing
diff --git a/src/pages/docs/platform/pricing/examples/ai-chatbot.mdx b/src/pages/docs/platform/pricing/examples/ai-chatbot.mdx
new file mode 100644
index 0000000000..38c849905a
--- /dev/null
+++ b/src/pages/docs/platform/pricing/examples/ai-chatbot.mdx
@@ -0,0 +1,52 @@
+---
+title: AI support chatbot pricing example
+meta_description: "Calculate AI Transport pricing for conversations with an AI chatbot. Example shows how using the message-per-response pattern and modifying the append rollup window can generate cost savings."
+meta_keywords: "chatbot, support chat, token streaming, token cost, AI Transport pricing, Ably AI Transport pricing, stream cost, Pub/Sub pricing, realtime data delivery, Ably Pub/Sub pricing"
+intro: "This example uses consumption-based pricing for an AI support chatbot use case, where a single agent is publishing tokens to user over AI Transport."
+---
+
+### Assumptions
+
+The scale and features used in this calculation.
+
+| Scale | Features |
+|-------|----------|
+| 4 user prompts to get to resolution | ✓ Message-per-response |
+| 300 token events per LLM response | |
+| 75 appends per second from agent | |
+| 3 minute average chat duration | |
+| 1 million chats | |
+
+### Cost summary
+
+The high level cost breakdown for this scenario is given in the table below. Messages are billed for both inbound (published to Ably) and outbound (delivered to subscribers). Enabling the "Message updates, deletes and appends" [channel rule](/docs/ai-transport/token-streaming/message-per-response#enable) will automatically enable message persistence.
+
+| Item | Calculation | Cost |
+|------|-------------|------|
+| Messages | 1212M × $2.50/M | $3030 |
+| Connection minutes | 6M × $1.00/M | $6 |
+| Channel minutes | 3M × $1.00/M | $3 |
+| Package fee | | [See plans](/pricing) |
+| **Total** | | **~$3039/M chats** |
+
+### Message usage breakdown
+
+Several factors influence the total message usage. The message-per-response pattern includes [automatic rollup of append events](/docs/ai-transport/token-streaming/token-rate-limits#per-response) to reduce consumption costs and avoid rate limits.
+
+- Agent stream time: 300 token events ÷ 75 appends per second = 4 seconds of streaming per response
+- Messages published after rollup: 4 seconds x 25 messages/s = **100 messages per response**
+
+| Type | Calculation | Inbound | Outbound | Total messages | Cost |
+|------|-------------|---------|----------|----------------|------|
+| User prompts | 1M chats × 4 prompts | 4M | 4M | 8M | $20 |
+| Agent responses | 1M chats x 4 responses x 100 messages per response | 400M | 400M | 800M | $2000 |
+| Persisted messages | Every inbound message is persisted | 404M | 0 | 404M | $1010 |
+| **Total** | | **808M** | **404M** | **1212M** | **$3030** |
+
+
+
diff --git a/writing-style-guide.md b/writing-style-guide.md
index ee739e7c67..68054b1b2c 100644
--- a/writing-style-guide.md
+++ b/writing-style-guide.md
@@ -235,6 +235,7 @@ Note the following points:
* The list should always have a piece of text introducing the list followed by a colon, and then a blank line.
* Each sentence in the list is terminated by a full-stop (period).
* If each item in the list is a single word, a terminating period is not required.
+* Do not use bold formatting for prefixes in bullet points (for example, avoid patterns like "**Feature name:** description"), as this is a common indicator of AI-generated content.
## Codeblocks
@@ -244,6 +245,8 @@ When inserting example code in the text:
* Break the text before a codeblock with a colon, not a period (which is a hard stop in the mind of the reader, rather than a continuation).
* There should *not* be a space before the colon.
* Place a blank line after the colon and before the code block.
+* All headings must be followed by introductory text. Never place a code block, list, or other content immediately after a heading without explanatory text first.
+* For JavaScript and TypeScript code, prefer single quotes over double quotes for strings (excluding JSON, which must use double quotes per the specification).
## Acronyms
@@ -274,6 +277,16 @@ Make sure you write the correct case for product names:
* GitHub not Github
* macOS not Mac OS
+## Avoid AI-generated content fingerprints
+
+Technical documentation should maintain a natural, human writing style and avoid patterns commonly associated with AI-generated content:
+
+* Do not use em-dashes (—) in technical writing. Prefer standard hyphens (-) or restructure the sentence for better clarity.
+* Avoid bold prefixes in bullet points (for example, patterns like "**Feature:** Description" or "**Benefits:** Details"). This formatting style is a telltale sign of AI-generated content.
+* Avoid formulaic patterns and overly structured prose that may appear mechanical or template-driven.
+
+These guidelines help ensure documentation feels authentic and professionally written while maintaining readability and clarity.
+
## Other considerations
Some additional points to bear in mind: