diff --git a/examples/ai-transport-message-per-response/javascript/README.md b/examples/ai-transport-message-per-response/javascript/README.md
new file mode 100644
index 0000000000..c0e3f41b66
--- /dev/null
+++ b/examples/ai-transport-message-per-response/javascript/README.md
@@ -0,0 +1,61 @@
+# AI Transport message per response streaming
+
+Enable realtime streaming of AI/LLM responses by appending tokens to a single message over Ably.
+
+AI Transport message-per-response streaming allows applications to provide immediate, responsive AI interactions by streaming tokens in realtime. Unlike the message-per-token pattern, all tokens for a response are appended to a single message, which appears as one entry in channel history. This makes it easy to retrieve and display conversation history while still delivering live tokens in realtime.
+
+The streaming approach significantly improves perceived performance and user engagement. Instead of waiting 5-10 seconds for a complete AI response, users see tokens appearing progressively, creating a more natural conversation flow similar to watching someone type in realtime.
+
+Token streaming is implemented using [Ably AI Transport](/docs/ai-transport). AI Transport provides purpose-built APIs for realtime AI applications, offering reliable message delivery, automatic ordering, and seamless reconnection handling to ensure no tokens are lost during network interruptions.
+
+## Resources
+
+Use the following methods to implement AI Transport message-per-response streaming:
+
+- [`client.channels.get()`](/docs/channels#create): creates a new or retrieves an existing channel for AI Transport token streaming.
+- [`channel.publish()`](/docs/channels#publish): publishes the initial message and captures the serial for token appending.
+- [`channel.appendMessage()`](/docs/messages#append): appends individual tokens to the message as they arrive from the LLM service.
+- [`channel.subscribe()`](/docs/channels#subscribe): subscribes to messages, handling `message.create`, `message.append`, and `message.update` actions.
+- [`channel.setOptions()`](/docs/channels/options) with [`rewind`](/docs/channels/options/rewind): enables seamless message recovery during reconnections, delivering historical messages as `message.update` events.
+
+Find out more about [AI Transport](/docs/ai-transport) and [message appending](/docs/ai-transport/features/token-streaming/message-per-response).
+
+## Getting started
+
+1. Clone the [Ably docs](https://github.com/ably/docs) repository where this example can be found:
+
+ ```sh
+ git clone git@github.com:ably/docs.git
+ ```
+
+2. Change directory:
+
+ ```sh
+ cd examples/
+ ```
+
+3. Rename the environment file:
+
+ ```sh
+ mv .env.example .env.local
+ ```
+
+4. In `.env.local` update the value of `VITE_ABLY_KEY` to be your Ably API key.
+
+5. Install dependencies:
+
+ ```sh
+ yarn install
+ ```
+
+6. Run the server:
+
+ ```sh
+ yarn run ai-transport-message-per-response-javascript
+ ```
+
+7. Try it out by opening [http://localhost:5173/](http://localhost:5173/) with your browser and selecting a prompt to see realtime AI token streaming.
+
+## Open in CodeSandbox
+
+In CodeSandbox, rename the `.env.example` file to `.env.local` and update the value of your `VITE_ABLY_KEY` variable to use your Ably API key.
diff --git a/examples/ai-transport-message-per-response/javascript/index.html b/examples/ai-transport-message-per-response/javascript/index.html
new file mode 100644
index 0000000000..b002b18e24
--- /dev/null
+++ b/examples/ai-transport-message-per-response/javascript/index.html
@@ -0,0 +1,49 @@
+
+
+
+
+
+
+ AI Transport Message Per Response - JavaScript
+
+
+
+
+
+
+
+
+
+
+
+ Ready
+
+
+
+
+
+
+ Select a prompt below to get started
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/examples/ai-transport-message-per-response/javascript/package.json b/examples/ai-transport-message-per-response/javascript/package.json
new file mode 100644
index 0000000000..710f1c4a12
--- /dev/null
+++ b/examples/ai-transport-message-per-response/javascript/package.json
@@ -0,0 +1,10 @@
+{
+ "name": "ai-transport-message-per-response-javascript",
+ "version": "1.0.0",
+ "type": "module",
+ "scripts": {
+ "dev": "vite",
+ "build": "vite build",
+ "preview": "vite preview"
+ }
+}
diff --git a/examples/ai-transport-message-per-response/javascript/src/agent.ts b/examples/ai-transport-message-per-response/javascript/src/agent.ts
new file mode 100644
index 0000000000..2c297e000f
--- /dev/null
+++ b/examples/ai-transport-message-per-response/javascript/src/agent.ts
@@ -0,0 +1,52 @@
+// Agent Service
+// This consumes LLM streams and publishes tokens using the message-per-response pattern
+// All tokens are appended to a single message, which appears as one entry in channel history
+
+import * as Ably from 'ably';
+import { MockLLM } from './llm';
+
+export class Agent {
+ private client: Ably.Realtime;
+ private channel: Ably.RealtimeChannel;
+ private llm: MockLLM;
+
+ constructor(ablyKey: string, channelName: string) {
+ this.client = new Ably.Realtime({
+ key: ablyKey,
+ clientId: 'ai-agent',
+ });
+ this.channel = this.client.channels.get(channelName);
+ this.llm = new MockLLM();
+ }
+
+ async processPrompt(prompt: string): Promise {
+ const stream = await this.llm.responses.create(prompt);
+ let msgSerial: string | null = null;
+
+ for await (const event of stream) {
+ if (event.type === 'message_start') {
+ // Create initial empty message and capture its serial
+ const publishResult = await this.channel.publish({
+ name: 'response',
+ data: '',
+ });
+ msgSerial = publishResult.serials[0];
+ } else if (event.type === 'message_delta') {
+ // Append each token to the same message using its serial
+ if (msgSerial && event.text) {
+ this.channel.appendMessage({
+ serial: msgSerial,
+ data: event.text,
+ });
+ }
+ } else if (event.type === 'message_stop') {
+ // Stream complete - all tokens have been appended
+ console.log('Response complete');
+ }
+ }
+ }
+
+ disconnect(): void {
+ this.client.close();
+ }
+}
diff --git a/examples/ai-transport-message-per-response/javascript/src/config.ts b/examples/ai-transport-message-per-response/javascript/src/config.ts
new file mode 100644
index 0000000000..8617022a2d
--- /dev/null
+++ b/examples/ai-transport-message-per-response/javascript/src/config.ts
@@ -0,0 +1,3 @@
+export const config = {
+ ABLY_KEY: import.meta.env.VITE_ABLY_KEY || 'YOUR_ABLY_KEY_HERE',
+};
diff --git a/examples/ai-transport-message-per-response/javascript/src/llm.ts b/examples/ai-transport-message-per-response/javascript/src/llm.ts
new file mode 100644
index 0000000000..ab9f1061f8
--- /dev/null
+++ b/examples/ai-transport-message-per-response/javascript/src/llm.ts
@@ -0,0 +1,49 @@
+// Mock LLM Service
+// This simulates a generic LLM SDK with streaming capabilities
+
+interface StreamEvent {
+ type: 'message_start' | 'message_delta' | 'message_stop';
+ text?: string;
+ responseId: string;
+}
+
+export class MockLLM {
+ private readonly responseText =
+ 'Ably AI Transport is a solution for building stateful, steerable, multi-device AI experiences into new or existing applications. You can use AI Transport as the transport layer with any LLM or agent framework, without rebuilding your existing stack or being locked to a particular vendor.';
+
+ responses = {
+ create: (prompt: string) => this.createStream(prompt),
+ };
+
+ private async *createStream(_prompt: string): AsyncIterable {
+ const responseId = `resp_${crypto.randomUUID()}`;
+
+ // Yield start event
+ yield { type: 'message_start', responseId };
+
+ // Chunk text into tokens (simulates LLM tokenization)
+ const tokens = this.chunkTextLikeAI(this.responseText);
+
+ for (const token of tokens) {
+ // Simulate realistic delay between tokens
+ await new Promise((resolve) => setTimeout(resolve, Math.random() * 150 + 50));
+
+ // Yield token event
+ yield { type: 'message_delta', text: token, responseId };
+ }
+
+ // Yield stop event
+ yield { type: 'message_stop', responseId };
+ }
+
+ private chunkTextLikeAI(text: string): string[] {
+ const chunks: string[] = [];
+ let pos = 0;
+ while (pos < text.length) {
+ const size = Math.floor(Math.random() * 8) + 1;
+ chunks.push(text.slice(pos, pos + size));
+ pos += size;
+ }
+ return chunks.filter((chunk) => chunk.length > 0);
+ }
+}
diff --git a/examples/ai-transport-message-per-response/javascript/src/script.ts b/examples/ai-transport-message-per-response/javascript/src/script.ts
new file mode 100644
index 0000000000..b8748377ab
--- /dev/null
+++ b/examples/ai-transport-message-per-response/javascript/src/script.ts
@@ -0,0 +1,96 @@
+import * as Ably from 'ably';
+import { Agent } from './agent';
+import { config } from './config';
+
+// Generate unique channel name for this session
+const CHANNEL_NAME = `ai:response-${crypto.randomUUID()}`;
+const client = new Ably.Realtime({
+ key: config.ABLY_KEY,
+});
+
+const channel = client.channels.get(CHANNEL_NAME);
+
+// Agent for processing prompts
+const agent = new Agent(config.ABLY_KEY, CHANNEL_NAME);
+
+// DOM elements
+const responseTextElement = document.getElementById('response-text') as HTMLDivElement;
+const connectionToggle = document.getElementById('connection-toggle') as HTMLButtonElement;
+const promptButton = document.getElementById('prompt-button') as HTMLButtonElement;
+const processingStatus = document.getElementById('processing-status') as HTMLSpanElement;
+
+// Track responses by message serial
+const responses = new Map();
+let currentSerial: string | null = null;
+
+const updateDisplay = () => {
+ if (currentSerial) {
+ responseTextElement.innerText = responses.get(currentSerial) || '';
+ }
+};
+
+// Subscribe to messages - rewind delivers history as message.update,
+// then seamlessly transitions to live message.append events
+channel.subscribe((message: Ably.Message) => {
+ const serial = message.serial;
+ if (!serial) {
+ return;
+ }
+
+ switch (message.action) {
+ case 'message.create':
+ responses.set(serial, message.data || '');
+ currentSerial = serial;
+ processingStatus.innerText = 'Streaming';
+ break;
+ case 'message.append': {
+ // Only append if this is for the current response
+ if (currentSerial === serial) {
+ const current = responses.get(serial) || '';
+ responses.set(serial, current + (message.data || ''));
+ }
+ break;
+ }
+ case 'message.update':
+ // Full state from history or resync - always use it
+ responses.set(serial, message.data || '');
+ currentSerial = serial;
+ break;
+ }
+ updateDisplay();
+});
+
+const handlePromptClick = () => {
+ currentSerial = null;
+ responseTextElement.innerText = '';
+ processingStatus.innerText = 'Streaming';
+
+ agent.processPrompt('What is Ably AI Transport?');
+};
+
+const handleConnect = async () => {
+ // Set rewind option before attaching to get history as message.update events
+ channel.setOptions({ params: { rewind: '2m' } });
+ await channel.attach();
+ connectionToggle.innerText = 'Disconnect';
+ processingStatus.innerText = 'Ready';
+};
+
+const handleDisconnect = async () => {
+ await channel.detach();
+ processingStatus.innerText = 'Paused';
+ connectionToggle.innerText = 'Connect';
+};
+
+const handleConnectionToggle = () => {
+ if (channel.state === 'attached') {
+ handleDisconnect();
+ } else {
+ handleConnect();
+ }
+};
+
+connectionToggle.onclick = handleConnectionToggle;
+promptButton.onclick = handlePromptClick;
+
+handleConnect();
diff --git a/examples/ai-transport-message-per-response/javascript/src/styles.css b/examples/ai-transport-message-per-response/javascript/src/styles.css
new file mode 100644
index 0000000000..b5c61c9567
--- /dev/null
+++ b/examples/ai-transport-message-per-response/javascript/src/styles.css
@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
diff --git a/examples/ai-transport-message-per-response/javascript/tailwind.config.ts b/examples/ai-transport-message-per-response/javascript/tailwind.config.ts
new file mode 100644
index 0000000000..1c86e1c371
--- /dev/null
+++ b/examples/ai-transport-message-per-response/javascript/tailwind.config.ts
@@ -0,0 +1,9 @@
+import baseConfig from '../../tailwind.config';
+import type { Config } from 'tailwindcss';
+
+const config: Config = {
+ ...baseConfig,
+ content: ['./src/**/*.{js,ts,tsx}', './index.html'],
+};
+
+export default config;
diff --git a/examples/ai-transport-message-per-response/javascript/vite.config.ts b/examples/ai-transport-message-per-response/javascript/vite.config.ts
new file mode 100644
index 0000000000..3b1cf13b4f
--- /dev/null
+++ b/examples/ai-transport-message-per-response/javascript/vite.config.ts
@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite';
+import baseConfig from '../../vite.config';
+
+export default defineConfig({
+ ...baseConfig,
+ envDir: '../../',
+});
diff --git a/examples/ai-transport-message-per-response/react/README.md b/examples/ai-transport-message-per-response/react/README.md
new file mode 100644
index 0000000000..bb10ac8f99
--- /dev/null
+++ b/examples/ai-transport-message-per-response/react/README.md
@@ -0,0 +1,70 @@
+# AI Transport message per response streaming
+
+Enable realtime streaming of AI/LLM responses using the message-per-response pattern, where all tokens are appended to a single Ably message.
+
+AI Transport message-per-response streaming allows applications to provide immediate, responsive AI interactions by streaming tokens in realtime while maintaining a clean message history. Each complete AI response appears as a single message in channel history, making it easy to retrieve and display multi-response conversation history.
+
+The streaming approach significantly improves perceived performance and user engagement. Instead of waiting 5-10 seconds for a complete AI response, users see tokens appearing progressively, creating a more natural conversation flow similar to watching someone type in realtime.
+
+Token streaming is implemented using [Ably AI Transport](/docs/ai-transport). AI Transport provides purpose-built APIs for realtime AI applications, offering reliable message delivery, automatic ordering, and seamless reconnection handling to ensure no tokens are lost during network interruptions.
+
+## Resources
+
+Use the following components to implement AI Transport message-per-response streaming:
+
+- [`AblyProvider`](/docs/getting-started/react-hooks#ably-provider): initializes and manages a shared Ably client instance, passing it down through React context to enable realtime AI Transport functionality across the application.
+- [`ChannelProvider`](/docs/getting-started/react-hooks#channel-provider): manages the state and functionality of a specific channel, providing access to AI response tokens and streaming state via React context.
+- [`useChannel()`](/docs/getting-started/react-hooks#useChannel) hook: a hook to subscribe to messages with `message.create`, `message.append`, and `message.update` actions.
+- [`rewind`](/docs/channels/options/rewind) channel option: enables seamless message recovery during reconnections, delivering historical messages as `message.update` events.
+- [`appendMessage()`](/docs/api/realtime-sdk/channels#append-message): appends tokens to an existing message using its serial.
+
+Find out more about [AI Transport](/docs/ai-transport) and [message-per-response](/docs/ai-transport/features/token-streaming/message-per-response).
+
+## Getting started
+
+1. Clone the [Ably docs](https://github.com/ably/docs) repository where this example can be found:
+
+ ```sh
+ git clone git@github.com:ably/docs.git
+ ```
+
+2. Change directory:
+
+ ```sh
+ cd examples/
+ ```
+
+3. Rename the environment file:
+
+ ```sh
+ mv .env.example .env.local
+ ```
+
+4. In `.env.local` update the value of `VITE_ABLY_KEY` to be your Ably API key.
+
+5. Install dependencies:
+
+ ```sh
+ yarn install
+ ```
+
+6. Run the server:
+
+ ```sh
+ yarn run ai-transport-message-per-response-react
+ ```
+
+7. Try it out by opening [http://localhost:5173/](http://localhost:5173/) with your browser and selecting a prompt to see realtime AI token streaming.
+
+## Open in CodeSandbox
+
+In CodeSandbox, rename the `.env.example` file to `.env.local` and update the value of your `VITE_ABLY_KEY` variable to use your Ably API key.
+
+## How it works
+
+The message-per-response pattern works by:
+
+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.
diff --git a/examples/ai-transport-message-per-response/react/index.html b/examples/ai-transport-message-per-response/react/index.html
new file mode 100644
index 0000000000..2c7da1dce4
--- /dev/null
+++ b/examples/ai-transport-message-per-response/react/index.html
@@ -0,0 +1,12 @@
+
+
+
+
+
+ AI Transport Message Per Response
+
+
+
+
+
+
diff --git a/examples/ai-transport-message-per-response/react/package.json b/examples/ai-transport-message-per-response/react/package.json
new file mode 100644
index 0000000000..efedff88ad
--- /dev/null
+++ b/examples/ai-transport-message-per-response/react/package.json
@@ -0,0 +1,10 @@
+{
+ "name": "ai-transport-message-per-response-react",
+ "version": "1.0.0",
+ "type": "module",
+ "scripts": {
+ "dev": "vite",
+ "build": "vite build",
+ "preview": "vite preview"
+ }
+}
diff --git a/examples/ai-transport-message-per-response/react/postcss.config.js b/examples/ai-transport-message-per-response/react/postcss.config.js
new file mode 100644
index 0000000000..2aa7205d4b
--- /dev/null
+++ b/examples/ai-transport-message-per-response/react/postcss.config.js
@@ -0,0 +1,6 @@
+export default {
+ plugins: {
+ tailwindcss: {},
+ autoprefixer: {},
+ },
+};
diff --git a/examples/ai-transport-message-per-response/react/src/App.tsx b/examples/ai-transport-message-per-response/react/src/App.tsx
new file mode 100644
index 0000000000..07bb4b730b
--- /dev/null
+++ b/examples/ai-transport-message-per-response/react/src/App.tsx
@@ -0,0 +1,151 @@
+import React, { useState } from 'react';
+import { AblyProvider, ChannelProvider, useChannel, useConnectionStateListener } from 'ably/react';
+import { Realtime, Message } from 'ably';
+import { Agent } from './agent';
+import { config } from './config';
+import './styles/styles.css';
+
+// Generate unique channel name for this session
+const CHANNEL_NAME = `ai:response-${crypto.randomUUID()}`;
+
+const client = new Realtime({
+ key: config.ABLY_KEY,
+});
+
+const AITransportDemo: React.FC = () => {
+ const [responses, setResponses] = useState>(new Map());
+ const [currentSerial, setCurrentSerial] = useState(null);
+ const [connectionState, setConnectionState] = useState('disconnected');
+ const [isChannelDetached, setIsChannelDetached] = useState(false);
+
+ // Agent persists across renders to avoid creating new connections
+ const agentRef = React.useRef(null);
+ if (!agentRef.current) {
+ agentRef.current = new Agent(config.ABLY_KEY, CHANNEL_NAME);
+ }
+
+ // Subscribe to messages on the channel
+ const { channel } = useChannel(CHANNEL_NAME, (message: Message) => {
+ const serial = message.serial;
+ if (!serial) {
+ return;
+ }
+
+ switch (message.action) {
+ case 'message.create':
+ // Initial message creation
+ setResponses((prev) => new Map(prev).set(serial, message.data || ''));
+ setCurrentSerial(serial);
+ break;
+ case 'message.append':
+ // Only append if this is for the current response
+ setCurrentSerial((current) => {
+ if (current === serial) {
+ setResponses((prev) => {
+ const newMap = new Map(prev);
+ const existing = newMap.get(serial) || '';
+ return newMap.set(serial, existing + (message.data || ''));
+ });
+ }
+ return current;
+ });
+ break;
+ case 'message.update':
+ // Full state from history (rewind) - replace existing data
+ setResponses((prev) => new Map(prev).set(serial, message.data || ''));
+ setCurrentSerial(serial);
+ break;
+ }
+ });
+
+ useConnectionStateListener((stateChange: { current: string }) => {
+ setConnectionState(stateChange.current);
+ });
+
+ const currentResponse = currentSerial ? responses.get(currentSerial) || '' : '';
+
+ const handlePromptClick = () => {
+ if (connectionState !== 'connected' || isChannelDetached) {
+ return;
+ }
+
+ setResponses(new Map());
+ setCurrentSerial(null);
+
+ agentRef.current?.processPrompt('What is Ably AI Transport?');
+ };
+
+ const handleDisconnect = () => {
+ channel.detach();
+ setIsChannelDetached(true);
+ };
+
+ const handleReconnect = async () => {
+ setIsChannelDetached(false);
+ // Set rewind option before reattaching to get history as message.update events
+ channel.setOptions({ params: { rewind: '2m' } });
+ await channel.attach();
+ };
+
+ return (
+
+ {/* Response section with always visible status */}
+