From ef2b1143ac29ed83d1ff132c5ac64ff713be51a7 Mon Sep 17 00:00:00 2001
From: matt423 <matthew.a423@gmail.com>
Date: Mon, 5 Jan 2026 11:38:46 +0000
Subject: [PATCH 01/15] chore: update message annotations terminology to
 include appends

---
 content/partials/types/_message.textile       | 131 ++++++++++++++++++
 .../token-streaming/message-per-response.mdx  |   4 +-
 2 files changed, 133 insertions(+), 2 deletions(-)
 create mode 100644 content/partials/types/_message.textile

diff --git a/content/partials/types/_message.textile b/content/partials/types/_message.textile
new file mode 100644
index 0000000000..272d7b8b28
--- /dev/null
+++ b/content/partials/types/_message.textile
@@ -0,0 +1,131 @@
+A @Message@ represents an individual message that is sent to or received from Ably.
+
+h6(#name).
+  default: name
+  csharp: Name
+
+The event name, if provided. <br>__Type: @String@__
+
+h6(#data).
+  default: data
+  csharp: Data
+
+The message payload, if provided.<br>__Type: <span lang="default">@String@, @StringBuffer@, @JSON Object@</span><span lang="java">@String@, @ByteArray@, @JSONObject@, @JSONArray@</span><span lang="csharp">@String@, @byte[]@, @plain C# object that can be serialized to JSON@</span><span lang="ruby">@String@, @Binary@ (ASCII-8BIT String), @Hash@, @Array@</span><span lang="python">@String@, @Bytearray@, @Dict@, @List@</span><span lang="php">@String@, @Binary String@, @Associative Array@, @Array@</span><span lang="objc">@NSString *@, @NSData *@, @NSDictionary *@, @NSArray *@</span><span lang="swift">@String@, @NSData@, @Dictionary@, @Array@</span><span lang="flutter">@String@, @Map@, @List@</span>__
+
+h6(#extras).
+  default: extras
+  csharp: Extras
+
+Metadata and/or ancillary payloads, if provided. Valid payloads include "@push@":/docs/push/publish#payload, "@headers@" (a map of strings to strings for arbitrary customer-supplied metadata), "@ephemeral@":/docs/pub-sub/advanced#ephemeral, and "@privileged@":/docs/platform/integrations/webhooks#skipping objects.<br>__Type: <span lang="java">@JSONObject@, @JSONArray@</span><span lang="csharp">plain C# object that can be converted to JSON</span><span lang="jsall">@JSON Object@</span><span lang="ruby">@Hash@, @Array@</span><span lang="python">@Dict@, @List@</span><span lang="swift">@Dictionary@, @Array@</span><span lang="objc">@NSDictionary *@, @NSArray *@</span><span lang="php">@Associative Array@, @Array@</span>__
+
+h6(#id).
+  default: id
+  csharp: Id
+
+A Unique ID assigned by Ably to this message.<br>__Type: @String@__
+
+h6(#client-id).
+  default: clientId
+  csharp: ClientId
+  ruby: client_id
+  python: client_id
+
+The client ID of the publisher of this message.<br>__Type: @String@__
+
+h6(#connection-id).
+  default: connectionId
+  csharp: ConnectionId
+  ruby: connection_id
+  python: connection_id
+
+The connection ID of the publisher of this message.<br>__Type: @String@__
+
+h6(#connection-key).
+  default: connectionKey
+  csharp,go: ConnectionKey
+  ruby,python: connection_key
+
+A connection key, which can optionally be included for a REST publish as part of the "publishing on behalf of a realtime client functionality":/docs/pub-sub/advanced#publish-on-behalf.<br>__Type: @String@__
+
+h6(#timestamp).
+  default: timestamp
+  csharp: Timestamp
+
+Timestamp when the message was first received by the Ably, as <span lang="default">milliseconds since the epoch</span><span lang="ruby">a @Time@ object</span><br>.__Type: <span lang="default">@Integer@</span><span lang="java">@Long Integer@</span><span lang="csharp">@DateTimeOffset@</span><span lang="ruby">@Time@</span><span lang="objc,swift">@NSDate@</span>__
+
+h6(#encoding).
+  default: encoding
+  csharp: Encoding
+
+This will typically be 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 will contain the remaining transformations not applied to the @data@ payload.<br>__Type: @String@__
+
+blang[jsall].
+
+  h6(#action).
+    default: action
+
+  The action type of the message, one of the "@MessageAction@":#message-action enum values.<br>__Type: @int enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY }@__
+
+  h6(#serial).
+    default: 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, deletes, and appends in "channel rules":/docs/channels#rules .<br>__Type: @String@__
+
+  h6(#annotations).
+    default: annotations
+
+  An object containing information about annotations that have been made to the object.<br>__Type: "@MessageAnnotations@":/docs/api/realtime-sdk/types#message-annotations__
+
+  h6(#version).
+    default: version
+
+  An object containing version metadata for messages that have been updated or deleted. See "updating and deleting messages":/docs/messages/updates-deletes for more information.<br>__Type: "@MessageVersion@":#message-version__
+
+h3(constructors).
+  default: Message constructors
+
+h6(#message-from-encoded).
+  default: Message.fromEncoded
+
+bq(definition).
+  default: Message.fromEncoded(Object encodedMsg, ChannelOptions channelOptions?) -> Message
+
+A static factory method to create a "@Message@":/docs/api/realtime-sdk/types#message from a deserialized @Message@-like object encoded using Ably's wire protocol.
+
+h4. Parameters
+
+- encodedMsg := a @Message@-like deserialized object.<br>__Type: @Object@__
+- channelOptions := an optional "@ChannelOptions@":/docs/api/realtime-sdk/types#channel-options. If you have an encrypted channel, use this to allow the library can decrypt the data.<br>__Type: @Object@__
+
+h4. Returns
+
+A "@Message@":/docs/api/realtime-sdk/types#message object
+
+h6(#message-from-encoded-array).
+  default: Message.fromEncodedArray
+
+bq(definition).
+  default: Message.fromEncodedArray(Object[] encodedMsgs, ChannelOptions channelOptions?) -> Message[]
+
+A static factory method to create an array of "@Messages@":/docs/api/realtime-sdk/types#message from an array of deserialized @Message@-like object encoded using Ably's wire protocol.
+
+h4. Parameters
+
+- encodedMsgs := an array of @Message@-like deserialized objects.<br>__Type: @Array@__
+- channelOptions := an optional "@ChannelOptions@":/docs/api/realtime-sdk/types#channel-options. If you have an encrypted channel, use this to allow the library can decrypt the data.<br>__Type: @Object@__
+
+h4. Returns
+
+An @Array@ of "@Message@":/docs/api/realtime-sdk/types#message objects
+
+h3(#message-version).
+  default: MessageVersion
+
+h4. Properties
+
+|_. Property |_. Description |_. Type |
+| serial | An Ably-generated ID that uniquely identifies this version of the message. Can be compared lexicographically to determine version ordering. For an original message with an action of @message.create@, this will be equal to the top-level @serial@. | @String@ |
+| timestamp | The time this version was created (when the update or delete operation was performed). For an original message, this will be equal to the top-level @timestamp@. | <span lang="default">@Integer@</span><span lang="java">@Long Integer@</span><span lang="csharp">@DateTimeOffset@</span><span lang="ruby">@Time@</span><span lang="objc,swift">@NSDate@</span> |
+| clientId | The client identifier of the user who performed the update or delete operation. Only present for @message.update@ and @message.delete@ actions. | @String@ (optional) |
+| description | Optional description provided when the update or delete was performed. Only present for @message.update@ and @message.delete@ actions. | @String@ (optional) |
+| metadata | Optional metadata provided when the update or delete was performed. Only present for @message.update@ and @message.delete@ actions. | @Object@ (optional) |
diff --git a/src/pages/docs/ai-transport/features/token-streaming/message-per-response.mdx b/src/pages/docs/ai-transport/features/token-streaming/message-per-response.mdx
index a501f562a6..86f7787dc1 100644
--- a/src/pages/docs/ai-transport/features/token-streaming/message-per-response.mdx
+++ b/src/pages/docs/ai-transport/features/token-streaming/message-per-response.mdx
@@ -22,7 +22,7 @@ Standard Ably message [size limits](/docs/platform/pricing/limits#message) apply
 
 ## Enable appends <a id="enable"/>
 
-Message append functionality requires "Message annotations, updates, deletes and appends" to be enabled in a [channel rule](/docs/channels#rules) associated with the channel.
+Message append functionality requires the "Message annotations, updates, deletes, and appends" [channel rule](/docs/channels#rules) enabled for your channel or [namespace](/docs/channels#namespaces).
 
 <Aside data-type="important">
 When the "Message updates and deletes" channel rule is enabled, messages are persisted irrespective of whether or not persistence has also been explicitly enabled. This will be reflected in increased usage since [we charge for persisting messages](https://faqs.ably.com/how-does-ably-count-messages).
@@ -34,7 +34,7 @@ To enable the channel rule:
 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.
+5. Select the "Message annotations, updates, deletes, and appends" rule 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:*`.

From 83315a2add212f172bfa3135ff43f4e66ef13a06 Mon Sep 17 00:00:00 2001
From: Fiona Corden <fiona.corden@ably.com>
Date: Sun, 14 Dec 2025 15:29:17 +0000
Subject: [PATCH 02/15] AI Transport overview page

General overview intro page for AIT, giving a summary of major feature groups
---
 src/pages/docs/ai-transport/index.mdx | 53 +++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/src/pages/docs/ai-transport/index.mdx b/src/pages/docs/ai-transport/index.mdx
index fb2f2b271e..c635f98ade 100644
--- a/src/pages/docs/ai-transport/index.mdx
+++ b/src/pages/docs/ai-transport/index.mdx
@@ -4,3 +4,56 @@ meta_description: "Learn more about Ably's AI Transport and the features that en
 redirect_from:
   - /docs/products/ai-transport
 ---
+
+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.
+
+## Key features
+
+AI Transport builds on [Ably Pub/Sub](/docs/basics) to enable reliable interactive AI experiences at scale and provides the following key features:
+
+// TODO: Check this lines up with planned doc sections
+* [Reliable, resumable token streams](#reliable-tokens)
+* [Session management](#session)
+* [Complex message patterns](#message)
+* [Enterprise controls](#enterprise)
+
+### Reliable, resumable token streams <a id="reliable-tokens"/>
+
+Ably AI Transport enables you to [stream tokens](/docs/ai-transport/features/token-streaming) reliably from your AI agent to your client devices using a channel. The token stream survives reconnections and token history is available for any new clients that connect.
+
+### Session management <a id="session"/>
+
+With AI Transport, communication between the client and agent is not tied to the connection state of either party. This gives you much more control over how to manage session lifetime and opens up opportunities for improved user experience, for example push notifications to offline users when a long-running task completes.
+
+// TODO: links
+
+### Complex message patterns <a id="message"/>
+
+Truly interactive AI experiences require more than a simple HTTP request-response exchange between a single client and agent. AI transport allows the use of [complex messaging patterns](//TODO: Link here), for example:
+* A user can communicate with multiple agents in a single channel and receive their responses simultaneously, along with any references or citations the model may supply.
+* A user can send additional requests or redirections while a response is in progress, instead of waiting until the response is complete.
+
+### Enterprise controls <a id="enterprise"/>
+
+Ably's platform provides [integrations](/docs/platform/integrations) and capabilities to ensure that your application will meet the requirements of enterprise environments, for example [message auditing](/docs/platform/integrations/streaming), [client identification](/docs/auth/identified-clients) and [RBAC](/docs/auth/capabilities).
+
+## Model SDKs and frameworks <a id="sdks-frameworks"/>
+
+Ably AI Transport can be used as the transport layer for any model or agent framework you choose to use in your stack, giving you full control of your technology decisions. Ably's how-to guides show example integrations with a selection of common SDKs and frameworks.
+
+// TODO: link these to our guides, or to their own docs? Also check that this list is accurate at the point we release
+* OpenAI Responses API
+* OpenAI Agents SDK
+* Claude Client SDK
+* Claude Agents SDK
+* LangChain
+* LangGraph
+* Vercel AI SDK Core
+
+If your chosen model or framework is not listed and you need additional help to design the integration with Ably then please contact [Support](/support).
+
+## Next steps
+
+Follow the Getting Started guides to learn more about Ably AI Transport and how it will work with your application.
+
+// TODO: Link to getting started and other documentation when available

From cb622fae76817ba0243f26eb51fd2885dd62d252 Mon Sep 17 00:00:00 2001
From: Fiona Corden <fiona.corden@ably.com>
Date: Sun, 14 Dec 2025 15:29:50 +0000
Subject: [PATCH 03/15] Token streaming intro

Overview page for token streaming - set direction, link to later pages
---
 src/data/nav/aitransport.ts                   |  5 ++
 .../features/token-streaming/index.mdx        | 49 +++++++++++++++++++
 2 files changed, 54 insertions(+)
 create mode 100644 src/pages/docs/ai-transport/features/token-streaming/index.mdx

diff --git a/src/data/nav/aitransport.ts b/src/data/nav/aitransport.ts
index cb8eeb5f11..42b206b6b7 100644
--- a/src/data/nav/aitransport.ts
+++ b/src/data/nav/aitransport.ts
@@ -21,6 +21,11 @@ export default {
     {
       name: 'Token streaming',
       pages: [
+        {
+          name: 'Overview',
+          link: '/docs/ai-transport/features/token-streaming',
+          index: true,
+        },
         {
           name: 'Message per response',
           link: '/docs/ai-transport/features/token-streaming/message-per-response',
diff --git a/src/pages/docs/ai-transport/features/token-streaming/index.mdx b/src/pages/docs/ai-transport/features/token-streaming/index.mdx
new file mode 100644
index 0000000000..7d108c318e
--- /dev/null
+++ b/src/pages/docs/ai-transport/features/token-streaming/index.mdx
@@ -0,0 +1,49 @@
+---
+title: Token streaming
+meta_description: "Learn about token streaming with Ably AI Transport, including common patterns and the features provided by the Ably solution."
+---
+
+Token streaming is a technique used with Large Language Models (LLMs) where the model's response is transmitted progressively as each token is generated, rather than waiting for the complete response before transmission begins. This allows users to see the response appear incrementally, similar to watching someone type in real-time, giving an improved user experience. This is normally accomplished by streaming the tokens as the response to an HTTP request from the client.
+
+// diagram of HTTP request/response
+
+If an HTTP stream is interrupted, for example because the client loses network connection, then any tokens that were transmitted during the interruption will be lost. Ably AI Transport solves this problem by streaming tokens to a [Pub/Sub channel](docs/channels), which is not tied to the connection state of either the client or the agent. A client that [reconnects](/docs/connect/states#connection-state-recovery) can receive any tokens transmitted while it was disconnected. If a new client connects, for example because the user has moved to a different device, then it is possible to hydrate the new client with all the tokens transmitted for the current request as well as the output from any previous requests. The exact mechanism for doing this will depend on which [token streaming pattern](#patterns) you choose to use.
+
+// diagram of Ably channel
+
+The Ably platform guarantees that messages will be [delivered in order](/docs/platform/architecture/message-ordering#ordering-guarantees) and [exactly once](/docs/platform/architecture/idempotency), so your client application does not have to handle duplicate or out-of-order messages.
+
+## Token streaming patterns <a id="patterns"/>
+
+Ably AI Transport is built on the Pub/Sub messaging platform, which allows you to use whatever message structure and pattern works best for your application. AI transport supports two token streaming patterns over realtime connections, so you can choose the one that best fits your requirements and customise it for your application.
+
+// TODO - find a reference link for realtime connections
+
+### Message-per-response <a id="pattern-per-response"/>
+Token streaming with [message-per-response](/docs/ai-transport/features/token-streaming/message-per-response) is a pattern where a complete response appears as one message in the channel history. The agent publishes the individual tokens over a realtime connection while the response is in progress and Ably concatenates the tokens into a single message in channel history. Connected clients receive the individual tokens messages as they are published. New clients will first receive a single message containing all the tokens that have been published for this response, followed by any newly published token messages.
+
+This pattern is useful when clients must always receive all tokens for the response and you need to efficiently rehydrate the client with a full conversation log. This is the recommended pattern for most applications.
+
+// diagram?
+
+### Message-per-token <a id="pattern-per-token"/>
+Token streaming with [message-per-token](/docs/ai-transport/features/token-streaming/message-per-token) is a pattern where every token generated by your model is published as its own Ably message. Each token then appears as one message in the channel history.
+
+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 the last few 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.
+
+// diagram?
+
+## Message events <a id="events"/>
+
+Different models and frameworks use different events to signal what is being sent to the client, for example start/stop events to mark the beginning and end of a streamed response. When you publish a message to an Ably channel, you can set the [message name](/docs/messages#properties) to the event type your client expects.
+
+## Next steps <a id="next"/>
+
+Read more about token streaming with the [message-per-response](/docs/ai-transport/features/token-streaming/message-per-response) and [message-per-token](/docs/ai-transport/features/token-streaming/message-per-token) patterns. Alternatively, check out the how-to guides to see how to implement these patterns with a variety of models and frameworks.
+
+// TODO: guide links

From 2d35e85195188a2fcf33b3ad08c5bf67252310af Mon Sep 17 00:00:00 2001
From: Fiona Corden <fiona.corden@ably.com>
Date: Mon, 15 Dec 2025 18:15:22 +0000
Subject: [PATCH 04/15] Update token streaming overview with diagram and align
 with compact history article

---
 .../features/token-streaming/index.mdx         | 18 ++++++------------
 1 file changed, 6 insertions(+), 12 deletions(-)

diff --git a/src/pages/docs/ai-transport/features/token-streaming/index.mdx b/src/pages/docs/ai-transport/features/token-streaming/index.mdx
index 7d108c318e..703d203a32 100644
--- a/src/pages/docs/ai-transport/features/token-streaming/index.mdx
+++ b/src/pages/docs/ai-transport/features/token-streaming/index.mdx
@@ -5,26 +5,22 @@ meta_description: "Learn about token streaming with Ably AI Transport, including
 
 Token streaming is a technique used with Large Language Models (LLMs) where the model's response is transmitted progressively as each token is generated, rather than waiting for the complete response before transmission begins. This allows users to see the response appear incrementally, similar to watching someone type in real-time, giving an improved user experience. This is normally accomplished by streaming the tokens as the response to an HTTP request from the client.
 
-// diagram of HTTP request/response
+![Ably AIT network diagram](../../../../../images/content/diagrams/ai-transport-before-and-after.png)
 
 If an HTTP stream is interrupted, for example because the client loses network connection, then any tokens that were transmitted during the interruption will be lost. Ably AI Transport solves this problem by streaming tokens to a [Pub/Sub channel](docs/channels), which is not tied to the connection state of either the client or the agent. A client that [reconnects](/docs/connect/states#connection-state-recovery) can receive any tokens transmitted while it was disconnected. If a new client connects, for example because the user has moved to a different device, then it is possible to hydrate the new client with all the tokens transmitted for the current request as well as the output from any previous requests. The exact mechanism for doing this will depend on which [token streaming pattern](#patterns) you choose to use.
 
-// diagram of Ably channel
-
 The Ably platform guarantees that messages will be [delivered in order](/docs/platform/architecture/message-ordering#ordering-guarantees) and [exactly once](/docs/platform/architecture/idempotency), so your client application does not have to handle duplicate or out-of-order messages.
 
 ## Token streaming patterns <a id="patterns"/>
 
-Ably AI Transport is built on the Pub/Sub messaging platform, which allows you to use whatever message structure and pattern works best for your application. AI transport supports two token streaming patterns over realtime connections, so you can choose the one that best fits your requirements and customise it for your application.
-
-// TODO - find a reference link for realtime connections
+Ably AI Transport is built on the Pub/Sub messaging platform, which allows you to use whatever message structure and pattern works best for your application. AI transport supports two token streaming patterns using a [Realtime](/docs/api/realtime-sdk) client,
+so you can choose the one that best fits your requirements and customise it for your application. The Realtime client 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).
 
 ### Message-per-response <a id="pattern-per-response"/>
-Token streaming with [message-per-response](/docs/ai-transport/features/token-streaming/message-per-response) is a pattern where a complete response appears as one message in the channel history. The agent publishes the individual tokens over a realtime connection while the response is in progress and Ably concatenates the tokens into a single message in channel history. Connected clients receive the individual tokens messages as they are published. New clients will first receive a single message containing all the tokens that have been published for this response, followed by any newly published token messages.
+Token streaming with [message-per-response](/docs/ai-transport/features/token-streaming/message-per-response) enables you to stream AI-generated content as individual tokens in realtime, while maintaining a clean, compacted message history. Each AI response becomes a single message on an Ably channel that grows as tokens are appended, resulting in efficient storage and easy retrieval of complete responses.
 
-This pattern is useful when clients must always receive all tokens for the response and you need to efficiently rehydrate the client with a full conversation log. This is the recommended pattern for most applications.
-
-// diagram?
+This pattern is the recommended approach for most applications. It is useful if you want clients joining mid-stream to catch up efficiently without receiving thousands of individual tokens and if clients build up a long conversation history that must be efficiently loaded on new or reconnecting devices.
 
 ### Message-per-token <a id="pattern-per-token"/>
 Token streaming with [message-per-token](/docs/ai-transport/features/token-streaming/message-per-token) is a pattern where every token generated by your model is published as its own Ably message. Each token then appears as one message in the channel history.
@@ -36,8 +32,6 @@ This pattern is useful when clients only care about the most recent part of a re
 - **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.
 
-// diagram?
-
 ## Message events <a id="events"/>
 
 Different models and frameworks use different events to signal what is being sent to the client, for example start/stop events to mark the beginning and end of a streamed response. When you publish a message to an Ably channel, you can set the [message name](/docs/messages#properties) to the event type your client expects.

From c68aa8e4fb8d3978e209c5dce6f40d389e3a6802 Mon Sep 17 00:00:00 2001
From: rainbowFi <fiona.corden@ably.com>
Date: Fri, 19 Dec 2025 16:45:16 +0000
Subject: [PATCH 05/15] Apply suggestions from code review

Co-authored-by: Paddy Byers <paddy.byers@gmail.com>
---
 .../ai-transport/features/token-streaming/index.mdx  | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/pages/docs/ai-transport/features/token-streaming/index.mdx b/src/pages/docs/ai-transport/features/token-streaming/index.mdx
index 703d203a32..c938fc0863 100644
--- a/src/pages/docs/ai-transport/features/token-streaming/index.mdx
+++ b/src/pages/docs/ai-transport/features/token-streaming/index.mdx
@@ -3,13 +3,13 @@ title: Token streaming
 meta_description: "Learn about token streaming with Ably AI Transport, including common patterns and the features provided by the Ably solution."
 ---
 
-Token streaming is a technique used with Large Language Models (LLMs) where the model's response is transmitted progressively as each token is generated, rather than waiting for the complete response before transmission begins. This allows users to see the response appear incrementally, similar to watching someone type in real-time, giving an improved user experience. This is normally accomplished by streaming the tokens as the response to an HTTP request from the client.
+Token streaming is a technique used with Large Language Models (LLMs) where the model's response is emitted progressively as each token is generated, rather than waiting for the complete response before transmission begins. This allows users to see the response appear incrementally, similar to watching someone type in real time, giving an improved user experience. This is normally accomplished by streaming the tokens as the response to an HTTP request from the client.
 
 ![Ably AIT network diagram](../../../../../images/content/diagrams/ai-transport-before-and-after.png)
 
 If an HTTP stream is interrupted, for example because the client loses network connection, then any tokens that were transmitted during the interruption will be lost. Ably AI Transport solves this problem by streaming tokens to a [Pub/Sub channel](docs/channels), which is not tied to the connection state of either the client or the agent. A client that [reconnects](/docs/connect/states#connection-state-recovery) can receive any tokens transmitted while it was disconnected. If a new client connects, for example because the user has moved to a different device, then it is possible to hydrate the new client with all the tokens transmitted for the current request as well as the output from any previous requests. The exact mechanism for doing this will depend on which [token streaming pattern](#patterns) you choose to use.
 
-The Ably platform guarantees that messages will be [delivered in order](/docs/platform/architecture/message-ordering#ordering-guarantees) and [exactly once](/docs/platform/architecture/idempotency), so your client application does not have to handle duplicate or out-of-order messages.
+The Ably platform guarantees that messages from a given realtime publisher will be [delivered in order](/docs/platform/architecture/message-ordering#ordering-guarantees) and [exactly once](/docs/platform/architecture/idempotency), so your client application does not have to handle duplicate or out-of-order messages.
 
 ## Token streaming patterns <a id="patterns"/>
 
@@ -18,23 +18,23 @@ so you can choose the one that best fits your requirements and customise it for
 while preserving guarantees around message delivery order. For more information, see [Realtime and REST](/docs/basics#realtime-and-rest).
 
 ### Message-per-response <a id="pattern-per-response"/>
-Token streaming with [message-per-response](/docs/ai-transport/features/token-streaming/message-per-response) enables you to stream AI-generated content as individual tokens in realtime, while maintaining a clean, compacted message history. Each AI response becomes a single message on an Ably channel that grows as tokens are appended, resulting in efficient storage and easy retrieval of complete responses.
+Token streaming with [message-per-response](/docs/ai-transport/features/token-streaming/message-per-response) enables you to stream LLM-generated content as individual tokens in realtime, while maintaining a clean, compacted message history. Each LLM response becomes a single message on an Ably channel that grows as tokens are appended, resulting in efficient storage and easy retrieval of complete responses.
 
 This pattern is the recommended approach for most applications. It is useful if you want clients joining mid-stream to catch up efficiently without receiving thousands of individual tokens and if clients build up a long conversation history that must be efficiently loaded on new or reconnecting devices.
 
 ### Message-per-token <a id="pattern-per-token"/>
-Token streaming with [message-per-token](/docs/ai-transport/features/token-streaming/message-per-token) is a pattern where every token generated by your model is published as its own Ably message. Each token then appears as one message in the channel history.
+Token streaming with [message-per-token](/docs/ai-transport/features/token-streaming/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 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 the last few tokens for the current "frame" of subtitles, not the entire transcript so far.
+- **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.
 
 ## Message events <a id="events"/>
 
-Different models and frameworks use different events to signal what is being sent to the client, for example start/stop events to mark the beginning and end of a streamed response. When you publish a message to an Ably channel, you can set the [message name](/docs/messages#properties) to the event type your client expects.
+Different models and frameworks use different events to signal what is being sent to the client, such as start/stop events to mark the beginning and end of a streamed response. When you publish a message to an Ably channel, you can set the [message name](/docs/messages#properties) to the event type your client expects.
 
 ## Next steps <a id="next"/>
 

From 130e8b50a3e6b8d83f8eafd447bbe79e4fa2638c Mon Sep 17 00:00:00 2001
From: Fiona Corden <fiona.corden@ably.com>
Date: Fri, 19 Dec 2025 16:48:42 +0000
Subject: [PATCH 06/15] Fixup: code review comments

---
 .../docs/ai-transport/features/token-streaming/index.mdx    | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/src/pages/docs/ai-transport/features/token-streaming/index.mdx b/src/pages/docs/ai-transport/features/token-streaming/index.mdx
index c938fc0863..ff6bf56c2c 100644
--- a/src/pages/docs/ai-transport/features/token-streaming/index.mdx
+++ b/src/pages/docs/ai-transport/features/token-streaming/index.mdx
@@ -7,15 +7,13 @@ Token streaming is a technique used with Large Language Models (LLMs) where the
 
 ![Ably AIT network diagram](../../../../../images/content/diagrams/ai-transport-before-and-after.png)
 
-If an HTTP stream is interrupted, for example because the client loses network connection, then any tokens that were transmitted during the interruption will be lost. Ably AI Transport solves this problem by streaming tokens to a [Pub/Sub channel](docs/channels), which is not tied to the connection state of either the client or the agent. A client that [reconnects](/docs/connect/states#connection-state-recovery) can receive any tokens transmitted while it was disconnected. If a new client connects, for example because the user has moved to a different device, then it is possible to hydrate the new client with all the tokens transmitted for the current request as well as the output from any previous requests. The exact mechanism for doing this will depend on which [token streaming pattern](#patterns) you choose to use.
+If an HTTP stream is interrupted, for example because the client loses network connection, then any tokens that were transmitted during the interruption will be lost. Ably AI Transport solves this problem by streaming tokens to a [Pub/Sub channel](docs/channels), which is not tied to the connection state of either the client or the agent. A client that [reconnects](/docs/connect/states#connection-state-recovery) can receive any tokens transmitted while it was disconnected. If a new client connects, for example because the user has moved to a different device, then it is possible to hydrate the new client with all the tokens transmitted for the current request as well as the output from any previous requests. In detail the mechanism for doing this will depend on which [token streaming pattern](#patterns) you choose to use.
 
 The Ably platform guarantees that messages from a given realtime publisher will be [delivered in order](/docs/platform/architecture/message-ordering#ordering-guarantees) and [exactly once](/docs/platform/architecture/idempotency), so your client application does not have to handle duplicate or out-of-order messages.
 
 ## Token streaming patterns <a id="patterns"/>
 
-Ably AI Transport is built on the Pub/Sub messaging platform, which allows you to use whatever message structure and pattern works best for your application. AI transport supports two token streaming patterns using a [Realtime](/docs/api/realtime-sdk) client,
-so you can choose the one that best fits your requirements and customise it for your application. The Realtime client 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).
+Ably AI Transport is built on the Pub/Sub messaging platform, which allows you to use whatever message structure and pattern works best for your application. AI transport supports two token streaming patterns using a [Realtime](/docs/api/realtime-sdk) client, so you can choose the one that best fits your requirements and customise it for your application. The Realtime client 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).
 
 ### Message-per-response <a id="pattern-per-response"/>
 Token streaming with [message-per-response](/docs/ai-transport/features/token-streaming/message-per-response) enables you to stream LLM-generated content as individual tokens in realtime, while maintaining a clean, compacted message history. Each LLM response becomes a single message on an Ably channel that grows as tokens are appended, resulting in efficient storage and easy retrieval of complete responses.

From a3f78c4941032a4054fa539dfde119b508315436 Mon Sep 17 00:00:00 2001
From: Fiona Corden <fiona.corden@ably.com>
Date: Mon, 5 Jan 2026 11:36:32 +0000
Subject: [PATCH 07/15] Fix-ups from review comments

---
 .../features/token-streaming/index.mdx          | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/src/pages/docs/ai-transport/features/token-streaming/index.mdx b/src/pages/docs/ai-transport/features/token-streaming/index.mdx
index ff6bf56c2c..b1d5d5c89a 100644
--- a/src/pages/docs/ai-transport/features/token-streaming/index.mdx
+++ b/src/pages/docs/ai-transport/features/token-streaming/index.mdx
@@ -7,7 +7,7 @@ Token streaming is a technique used with Large Language Models (LLMs) where the
 
 ![Ably AIT network diagram](../../../../../images/content/diagrams/ai-transport-before-and-after.png)
 
-If an HTTP stream is interrupted, for example because the client loses network connection, then any tokens that were transmitted during the interruption will be lost. Ably AI Transport solves this problem by streaming tokens to a [Pub/Sub channel](docs/channels), which is not tied to the connection state of either the client or the agent. A client that [reconnects](/docs/connect/states#connection-state-recovery) can receive any tokens transmitted while it was disconnected. If a new client connects, for example because the user has moved to a different device, then it is possible to hydrate the new client with all the tokens transmitted for the current request as well as the output from any previous requests. In detail the mechanism for doing this will depend on which [token streaming pattern](#patterns) you choose to use.
+If an HTTP stream is interrupted, for example because the client loses network connection, then any tokens that were transmitted during the interruption will be lost. Ably AI Transport solves this problem by streaming tokens to a [Pub/Sub channel](docs/channels), which is not tied to the connection state of either the client or the agent. A client that [reconnects](/docs/connect/states#connection-state-recovery) can receive any tokens transmitted while it was disconnected. If a new client connects, for example because the user has moved to a different device, then it is possible to hydrate the new client with all the tokens transmitted for the current request as well as the output from any previous requests. The detailed mechanism for doing this will depend on which [token streaming pattern](#patterns) you choose to use.
 
 The Ably platform guarantees that messages from a given realtime publisher will be [delivered in order](/docs/platform/architecture/message-ordering#ordering-guarantees) and [exactly once](/docs/platform/architecture/idempotency), so your client application does not have to handle duplicate or out-of-order messages.
 
@@ -18,17 +18,20 @@ Ably AI Transport is built on the Pub/Sub messaging platform, which allows you t
 ### Message-per-response <a id="pattern-per-response"/>
 Token streaming with [message-per-response](/docs/ai-transport/features/token-streaming/message-per-response) enables you to stream LLM-generated content as individual tokens in realtime, while maintaining a clean, compacted message history. Each LLM response becomes a single message on an Ably channel that grows as tokens are appended, resulting in efficient storage and easy retrieval of complete responses.
 
-This pattern is the recommended approach for most applications. It is useful if you want clients joining mid-stream to catch up efficiently without receiving thousands of individual tokens and if clients build up a long conversation history that must be efficiently loaded on new or reconnecting devices.
+This pattern is the recommended approach for most applications. It is useful if you want clients joining mid-stream to catch up efficiently without receiving thousands of individual tokens and if clients build up a long conversation history that must be efficiently loaded on new or reconnecting devices. For example:
+
+- Chat experiences: The full chat history must be replayed from Ably whenever the user changes device or when a new participant joins the chat, allowing both users and agents to maintain context.
+- Long-running and asynchronous tasks: Users need to catch up quickly when they reconnect to check progress throughout the task lifetime, but do not need to receive the individual tokens that make up the response.
+- Backend-stored responses: The backend writes complete responses to a database and clients load those full responses from there, while Ably is used to deliver the current in-progress response.
 
 ### Message-per-token <a id="pattern-per-token"/>
 Token streaming with [message-per-token](/docs/ai-transport/features/token-streaming/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 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:
+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, or if you need to preserve the specific token fragmentation that was generated by the model. 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.
+- 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.
 
 ## Message events <a id="events"/>
 

From 3719abb8a832ab271bbe07e0d831a90202b5fbff Mon Sep 17 00:00:00 2001
From: Fiona Corden <fiona.corden@ably.com>
Date: Mon, 5 Jan 2026 14:47:49 +0000
Subject: [PATCH 08/15] Update overview page with notes

---
 src/pages/docs/ai-transport/index.mdx | 41 ++++++++++++++-------------
 1 file changed, 21 insertions(+), 20 deletions(-)

diff --git a/src/pages/docs/ai-transport/index.mdx b/src/pages/docs/ai-transport/index.mdx
index c635f98ade..2a7261079f 100644
--- a/src/pages/docs/ai-transport/index.mdx
+++ b/src/pages/docs/ai-transport/index.mdx
@@ -5,43 +5,42 @@ redirect_from:
   - /docs/products/ai-transport
 ---
 
-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.
+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.
 
 ## Key features
 
 AI Transport builds on [Ably Pub/Sub](/docs/basics) to enable reliable interactive AI experiences at scale and provides the following key features:
 
-// TODO: Check this lines up with planned doc sections
-* [Reliable, resumable token streams](#reliable-tokens)
-* [Session management](#session)
-* [Complex message patterns](#message)
-* [Enterprise controls](#enterprise)
-
 ### Reliable, resumable token streams <a id="reliable-tokens"/>
 
-Ably AI Transport enables you to [stream tokens](/docs/ai-transport/features/token-streaming) reliably from your AI agent to your client devices using a channel. The token stream survives reconnections and token history is available for any new clients that connect.
-
-### Session management <a id="session"/>
-
-With AI Transport, communication between the client and agent is not tied to the connection state of either party. This gives you much more control over how to manage session lifetime and opens up opportunities for improved user experience, for example push notifications to offline users when a long-running task completes.
+Ably AI Transport enables you to [stream tokens](/docs/ai-transport/features/token-streaming) reliably from your AI agent to your client devices. The token stream survives reconnections thanks to Ably's [connection recovery](/docs/platform/architecture/connection-recovery) capabilities, so your clients don't miss anything. If the user has multiple devices or tabs then the stream history stays in sync across all of them, with no additional work from your application, and a new client can quickly catch up on both past responses and the current in-progress response.
 
-// TODO: links
+### Messaging patterns <a id="messages"/>
 
-### Complex message patterns <a id="message"/>
-
-Truly interactive AI experiences require more than a simple HTTP request-response exchange between a single client and agent. AI transport allows the use of [complex messaging patterns](//TODO: Link here), for example:
+Truly interactive AI experiences require more than a simple HTTP request-response exchange between a single client and agent. AI transport allows the use of different [messaging patterns](/docs/ai-transport/features/messaging), for example:
 * A user can communicate with multiple agents in a single channel and receive their responses simultaneously, along with any references or citations the model may supply.
 * A user can send additional requests or redirections while a response is in progress, instead of waiting until the response is complete.
+* Human-in-the-loop interactions, such as requests for tool call permissions or further information, can be easily implemented and form part of the conversation history for future reference.
+* A new participant joining the conversation, for example a customer support representative, can see the full chat history without asking the user to repeat information.
+
+### Session management <a id="session"/>
+
+With AI Transport, communication between the client and agent is not tied to the connection state of either party. This gives you much more control over how to manage [session lifetime](/docs/ai-transport/features/session-management) and opens up opportunities for improved user experience, for example sending [push notifications](/docs/push) to offline users when a long-running task completes.
 
 ### Enterprise controls <a id="enterprise"/>
 
-Ably's platform provides [integrations](/docs/platform/integrations) and capabilities to ensure that your application will meet the requirements of enterprise environments, for example [message auditing](/docs/platform/integrations/streaming), [client identification](/docs/auth/identified-clients) and [RBAC](/docs/auth/capabilities).
+Ably's platform provides [integrations](/docs/platform/integrations) and capabilities to ensure that your application will meet the requirements of enterprise environments, for example [message auditing](/docs/platform/integrations/streaming), [client identification](/docs/auth/identified-clients) and [RBAC capabilities](/docs/auth/capabilities).
+
+## Why Ably AI Transport
+
+- global
+- reliable
+- scale
 
 ## Model SDKs and frameworks <a id="sdks-frameworks"/>
 
 Ably AI Transport can be used as the transport layer for any model or agent framework you choose to use in your stack, giving you full control of your technology decisions. Ably's how-to guides show example integrations with a selection of common SDKs and frameworks.
 
-// TODO: link these to our guides, or to their own docs? Also check that this list is accurate at the point we release
 * OpenAI Responses API
 * OpenAI Agents SDK
 * Claude Client SDK
@@ -52,8 +51,10 @@ Ably AI Transport can be used as the transport layer for any model or agent fram
 
 If your chosen model or framework is not listed and you need additional help to design the integration with Ably then please contact [Support](/support).
 
+## Pricing
+
+We are working on an updated pricing model for AI Transport, so watch this space! The current Ably Pub/Sub [pricing model](/docs/platform/pricing) will apply until then, but please [contact us](/contact) if this will not meet your needs.
+
 ## Next steps
 
 Follow the Getting Started guides to learn more about Ably AI Transport and how it will work with your application.
-
-// TODO: Link to getting started and other documentation when available

From 3e3bed883dc7bba7cbdc0c4819d1b974ae0cb099 Mon Sep 17 00:00:00 2001
From: Fiona Corden <fiona.corden@ably.com>
Date: Tue, 6 Jan 2026 09:58:20 +0000
Subject: [PATCH 09/15] Remove product overview page, which will be separate PR

---
 src/pages/docs/ai-transport/index.mdx | 60 ---------------------------
 1 file changed, 60 deletions(-)
 delete mode 100644 src/pages/docs/ai-transport/index.mdx

diff --git a/src/pages/docs/ai-transport/index.mdx b/src/pages/docs/ai-transport/index.mdx
deleted file mode 100644
index 2a7261079f..0000000000
--- a/src/pages/docs/ai-transport/index.mdx
+++ /dev/null
@@ -1,60 +0,0 @@
----
-title: About AI Transport
-meta_description: "Learn more about Ably's AI Transport and the features that enable you to quickly build functionality into new and existing applications."
-redirect_from:
-  - /docs/products/ai-transport
----
-
-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.
-
-## Key features
-
-AI Transport builds on [Ably Pub/Sub](/docs/basics) to enable reliable interactive AI experiences at scale and provides the following key features:
-
-### Reliable, resumable token streams <a id="reliable-tokens"/>
-
-Ably AI Transport enables you to [stream tokens](/docs/ai-transport/features/token-streaming) reliably from your AI agent to your client devices. The token stream survives reconnections thanks to Ably's [connection recovery](/docs/platform/architecture/connection-recovery) capabilities, so your clients don't miss anything. If the user has multiple devices or tabs then the stream history stays in sync across all of them, with no additional work from your application, and a new client can quickly catch up on both past responses and the current in-progress response.
-
-### Messaging patterns <a id="messages"/>
-
-Truly interactive AI experiences require more than a simple HTTP request-response exchange between a single client and agent. AI transport allows the use of different [messaging patterns](/docs/ai-transport/features/messaging), for example:
-* A user can communicate with multiple agents in a single channel and receive their responses simultaneously, along with any references or citations the model may supply.
-* A user can send additional requests or redirections while a response is in progress, instead of waiting until the response is complete.
-* Human-in-the-loop interactions, such as requests for tool call permissions or further information, can be easily implemented and form part of the conversation history for future reference.
-* A new participant joining the conversation, for example a customer support representative, can see the full chat history without asking the user to repeat information.
-
-### Session management <a id="session"/>
-
-With AI Transport, communication between the client and agent is not tied to the connection state of either party. This gives you much more control over how to manage [session lifetime](/docs/ai-transport/features/session-management) and opens up opportunities for improved user experience, for example sending [push notifications](/docs/push) to offline users when a long-running task completes.
-
-### Enterprise controls <a id="enterprise"/>
-
-Ably's platform provides [integrations](/docs/platform/integrations) and capabilities to ensure that your application will meet the requirements of enterprise environments, for example [message auditing](/docs/platform/integrations/streaming), [client identification](/docs/auth/identified-clients) and [RBAC capabilities](/docs/auth/capabilities).
-
-## Why Ably AI Transport
-
-- global
-- reliable
-- scale
-
-## Model SDKs and frameworks <a id="sdks-frameworks"/>
-
-Ably AI Transport can be used as the transport layer for any model or agent framework you choose to use in your stack, giving you full control of your technology decisions. Ably's how-to guides show example integrations with a selection of common SDKs and frameworks.
-
-* OpenAI Responses API
-* OpenAI Agents SDK
-* Claude Client SDK
-* Claude Agents SDK
-* LangChain
-* LangGraph
-* Vercel AI SDK Core
-
-If your chosen model or framework is not listed and you need additional help to design the integration with Ably then please contact [Support](/support).
-
-## Pricing
-
-We are working on an updated pricing model for AI Transport, so watch this space! The current Ably Pub/Sub [pricing model](/docs/platform/pricing) will apply until then, but please [contact us](/contact) if this will not meet your needs.
-
-## Next steps
-
-Follow the Getting Started guides to learn more about Ably AI Transport and how it will work with your application.

From 49651af7cbfee3b88008f0fddf02cb187b21a2be Mon Sep 17 00:00:00 2001
From: Fiona Corden <fiona.corden@ably.com>
Date: Tue, 6 Jan 2026 09:59:40 +0000
Subject: [PATCH 10/15] Revert "Remove product overview page, which will be
 separate PR"

This reverts commit 78b041126b2be6edcda8fbf6a75878159fb67fc3.
---
 src/pages/docs/ai-transport/index.mdx | 60 +++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 src/pages/docs/ai-transport/index.mdx

diff --git a/src/pages/docs/ai-transport/index.mdx b/src/pages/docs/ai-transport/index.mdx
new file mode 100644
index 0000000000..2a7261079f
--- /dev/null
+++ b/src/pages/docs/ai-transport/index.mdx
@@ -0,0 +1,60 @@
+---
+title: About AI Transport
+meta_description: "Learn more about Ably's AI Transport and the features that enable you to quickly build functionality into new and existing applications."
+redirect_from:
+  - /docs/products/ai-transport
+---
+
+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.
+
+## Key features
+
+AI Transport builds on [Ably Pub/Sub](/docs/basics) to enable reliable interactive AI experiences at scale and provides the following key features:
+
+### Reliable, resumable token streams <a id="reliable-tokens"/>
+
+Ably AI Transport enables you to [stream tokens](/docs/ai-transport/features/token-streaming) reliably from your AI agent to your client devices. The token stream survives reconnections thanks to Ably's [connection recovery](/docs/platform/architecture/connection-recovery) capabilities, so your clients don't miss anything. If the user has multiple devices or tabs then the stream history stays in sync across all of them, with no additional work from your application, and a new client can quickly catch up on both past responses and the current in-progress response.
+
+### Messaging patterns <a id="messages"/>
+
+Truly interactive AI experiences require more than a simple HTTP request-response exchange between a single client and agent. AI transport allows the use of different [messaging patterns](/docs/ai-transport/features/messaging), for example:
+* A user can communicate with multiple agents in a single channel and receive their responses simultaneously, along with any references or citations the model may supply.
+* A user can send additional requests or redirections while a response is in progress, instead of waiting until the response is complete.
+* Human-in-the-loop interactions, such as requests for tool call permissions or further information, can be easily implemented and form part of the conversation history for future reference.
+* A new participant joining the conversation, for example a customer support representative, can see the full chat history without asking the user to repeat information.
+
+### Session management <a id="session"/>
+
+With AI Transport, communication between the client and agent is not tied to the connection state of either party. This gives you much more control over how to manage [session lifetime](/docs/ai-transport/features/session-management) and opens up opportunities for improved user experience, for example sending [push notifications](/docs/push) to offline users when a long-running task completes.
+
+### Enterprise controls <a id="enterprise"/>
+
+Ably's platform provides [integrations](/docs/platform/integrations) and capabilities to ensure that your application will meet the requirements of enterprise environments, for example [message auditing](/docs/platform/integrations/streaming), [client identification](/docs/auth/identified-clients) and [RBAC capabilities](/docs/auth/capabilities).
+
+## Why Ably AI Transport
+
+- global
+- reliable
+- scale
+
+## Model SDKs and frameworks <a id="sdks-frameworks"/>
+
+Ably AI Transport can be used as the transport layer for any model or agent framework you choose to use in your stack, giving you full control of your technology decisions. Ably's how-to guides show example integrations with a selection of common SDKs and frameworks.
+
+* OpenAI Responses API
+* OpenAI Agents SDK
+* Claude Client SDK
+* Claude Agents SDK
+* LangChain
+* LangGraph
+* Vercel AI SDK Core
+
+If your chosen model or framework is not listed and you need additional help to design the integration with Ably then please contact [Support](/support).
+
+## Pricing
+
+We are working on an updated pricing model for AI Transport, so watch this space! The current Ably Pub/Sub [pricing model](/docs/platform/pricing) will apply until then, but please [contact us](/contact) if this will not meet your needs.
+
+## Next steps
+
+Follow the Getting Started guides to learn more about Ably AI Transport and how it will work with your application.

From eb0ec47e548554685ee3c83499e8df521d275128 Mon Sep 17 00:00:00 2001
From: Fiona Corden <fiona.corden@ably.com>
Date: Tue, 6 Jan 2026 10:00:34 +0000
Subject: [PATCH 11/15] Revert overview to match base branch, will be separate
 PR

---
 src/pages/docs/ai-transport/index.mdx | 54 ---------------------------
 1 file changed, 54 deletions(-)

diff --git a/src/pages/docs/ai-transport/index.mdx b/src/pages/docs/ai-transport/index.mdx
index 2a7261079f..fb2f2b271e 100644
--- a/src/pages/docs/ai-transport/index.mdx
+++ b/src/pages/docs/ai-transport/index.mdx
@@ -4,57 +4,3 @@ meta_description: "Learn more about Ably's AI Transport and the features that en
 redirect_from:
   - /docs/products/ai-transport
 ---
-
-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.
-
-## Key features
-
-AI Transport builds on [Ably Pub/Sub](/docs/basics) to enable reliable interactive AI experiences at scale and provides the following key features:
-
-### Reliable, resumable token streams <a id="reliable-tokens"/>
-
-Ably AI Transport enables you to [stream tokens](/docs/ai-transport/features/token-streaming) reliably from your AI agent to your client devices. The token stream survives reconnections thanks to Ably's [connection recovery](/docs/platform/architecture/connection-recovery) capabilities, so your clients don't miss anything. If the user has multiple devices or tabs then the stream history stays in sync across all of them, with no additional work from your application, and a new client can quickly catch up on both past responses and the current in-progress response.
-
-### Messaging patterns <a id="messages"/>
-
-Truly interactive AI experiences require more than a simple HTTP request-response exchange between a single client and agent. AI transport allows the use of different [messaging patterns](/docs/ai-transport/features/messaging), for example:
-* A user can communicate with multiple agents in a single channel and receive their responses simultaneously, along with any references or citations the model may supply.
-* A user can send additional requests or redirections while a response is in progress, instead of waiting until the response is complete.
-* Human-in-the-loop interactions, such as requests for tool call permissions or further information, can be easily implemented and form part of the conversation history for future reference.
-* A new participant joining the conversation, for example a customer support representative, can see the full chat history without asking the user to repeat information.
-
-### Session management <a id="session"/>
-
-With AI Transport, communication between the client and agent is not tied to the connection state of either party. This gives you much more control over how to manage [session lifetime](/docs/ai-transport/features/session-management) and opens up opportunities for improved user experience, for example sending [push notifications](/docs/push) to offline users when a long-running task completes.
-
-### Enterprise controls <a id="enterprise"/>
-
-Ably's platform provides [integrations](/docs/platform/integrations) and capabilities to ensure that your application will meet the requirements of enterprise environments, for example [message auditing](/docs/platform/integrations/streaming), [client identification](/docs/auth/identified-clients) and [RBAC capabilities](/docs/auth/capabilities).
-
-## Why Ably AI Transport
-
-- global
-- reliable
-- scale
-
-## Model SDKs and frameworks <a id="sdks-frameworks"/>
-
-Ably AI Transport can be used as the transport layer for any model or agent framework you choose to use in your stack, giving you full control of your technology decisions. Ably's how-to guides show example integrations with a selection of common SDKs and frameworks.
-
-* OpenAI Responses API
-* OpenAI Agents SDK
-* Claude Client SDK
-* Claude Agents SDK
-* LangChain
-* LangGraph
-* Vercel AI SDK Core
-
-If your chosen model or framework is not listed and you need additional help to design the integration with Ably then please contact [Support](/support).
-
-## Pricing
-
-We are working on an updated pricing model for AI Transport, so watch this space! The current Ably Pub/Sub [pricing model](/docs/platform/pricing) will apply until then, but please [contact us](/contact) if this will not meet your needs.
-
-## Next steps
-
-Follow the Getting Started guides to learn more about Ably AI Transport and how it will work with your application.

From ee4ba8a3b7d06fefe1440b3b43898a2d63f16521 Mon Sep 17 00:00:00 2001
From: Fiona Corden <fiona.corden@ably.com>
Date: Fri, 9 Jan 2026 10:00:24 +0000
Subject: [PATCH 12/15] Fixup: update overview based on feedback

---
 .../features/token-streaming/index.mdx        | 73 +++++++++++++------
 1 file changed, 51 insertions(+), 22 deletions(-)

diff --git a/src/pages/docs/ai-transport/features/token-streaming/index.mdx b/src/pages/docs/ai-transport/features/token-streaming/index.mdx
index b1d5d5c89a..7deff6480d 100644
--- a/src/pages/docs/ai-transport/features/token-streaming/index.mdx
+++ b/src/pages/docs/ai-transport/features/token-streaming/index.mdx
@@ -3,42 +3,71 @@ title: Token streaming
 meta_description: "Learn about token streaming with Ably AI Transport, including common patterns and the features provided by the Ably solution."
 ---
 
-Token streaming is a technique used with Large Language Models (LLMs) where the model's response is emitted progressively as each token is generated, rather than waiting for the complete response before transmission begins. This allows users to see the response appear incrementally, similar to watching someone type in real time, giving an improved user experience. This is normally accomplished by streaming the tokens as the response to an HTTP request from the client.
+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.
+
+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.
 
 ![Ably AIT network diagram](../../../../../images/content/diagrams/ai-transport-before-and-after.png)
 
-If an HTTP stream is interrupted, for example because the client loses network connection, then any tokens that were transmitted during the interruption will be lost. Ably AI Transport solves this problem by streaming tokens to a [Pub/Sub channel](docs/channels), which is not tied to the connection state of either the client or the agent. A client that [reconnects](/docs/connect/states#connection-state-recovery) can receive any tokens transmitted while it was disconnected. If a new client connects, for example because the user has moved to a different device, then it is possible to hydrate the new client with all the tokens transmitted for the current request as well as the output from any previous requests. The detailed mechanism for doing this will depend on which [token streaming pattern](#patterns) you choose to use.
+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 or 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 |
+| Browser crash | 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 |
+
+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/features/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.
 
-The Ably platform guarantees that messages from a given realtime publisher will be [delivered in order](/docs/platform/architecture/message-ordering#ordering-guarantees) and [exactly once](/docs/platform/architecture/idempotency), so your client application does not have to handle duplicate or out-of-order messages.
+This pattern is the recommended approach for most applications. It excels when:
 
-## Token streaming patterns <a id="patterns"/>
+- 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
 
-Ably AI Transport is built on the Pub/Sub messaging platform, which allows you to use whatever message structure and pattern works best for your application. AI transport supports two token streaming patterns using a [Realtime](/docs/api/realtime-sdk) client, so you can choose the one that best fits your requirements and customise it for your application. The Realtime client 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).
+Example use cases:
 
-### Message-per-response <a id="pattern-per-response"/>
-Token streaming with [message-per-response](/docs/ai-transport/features/token-streaming/message-per-response) enables you to stream LLM-generated content as individual tokens in realtime, while maintaining a clean, compacted message history. Each LLM response becomes a single message on an Ably channel that grows as tokens are appended, resulting in efficient storage and easy retrieval of complete responses.
+- **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.
 
-This pattern is the recommended approach for most applications. It is useful if you want clients joining mid-stream to catch up efficiently without receiving thousands of individual tokens and if clients build up a long conversation history that must be efficiently loaded on new or reconnecting devices. For example:
+### Message-per-token
 
-- Chat experiences: The full chat history must be replayed from Ably whenever the user changes device or when a new participant joins the chat, allowing both users and agents to maintain context.
-- Long-running and asynchronous tasks: Users need to catch up quickly when they reconnect to check progress throughout the task lifetime, but do not need to receive the individual tokens that make up the response.
-- Backend-stored responses: The backend writes complete responses to a database and clients load those full responses from there, while Ably is used to deliver the current in-progress response.
+[Message-per-token](/docs/ai-transport/features/token-streaming/message-per-token) publishes every generated token as an independent Ably message. Each token appears as a separate message in channel history.
 
-### Message-per-token <a id="pattern-per-token"/>
-Token streaming with [message-per-token](/docs/ai-transport/features/token-streaming/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 pattern is useful when:
 
-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, or if you need to preserve the specific token fragmentation that was generated by the model. For example:
+- 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
 
-- 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.
+Example use cases:
 
-## Message events <a id="events"/>
+- **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.
 
-Different models and frameworks use different events to signal what is being sent to the client, such as start/stop events to mark the beginning and end of a streamed response. When you publish a message to an Ably channel, you can set the [message name](/docs/messages#properties) to the event type your client expects.
+## Message events
 
-## Next steps <a id="next"/>
+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, set the [message name](/docs/messages#properties) to the event type your client expects. This allows your frontend to handle each event type appropriately without parsing message content.
 
-Read more about token streaming with the [message-per-response](/docs/ai-transport/features/token-streaming/message-per-response) and [message-per-token](/docs/ai-transport/features/token-streaming/message-per-token) patterns. Alternatively, check out the how-to guides to see how to implement these patterns with a variety of models and frameworks.
+## Next steps
 
-// TODO: guide links
+- Implement token streaming with [message-per-response](/docs/ai-transport/features/token-streaming/message-per-response) (recommended for most applications)
+- Implement token streaming with [message-per-token](/docs/ai-transport/features/token-streaming/message-per-token) for sliding-window use cases
+- Explore the guides for integration with specific models and frameworks

From 8823caf20144b6a61c2e03f39810a73c53f41ca5 Mon Sep 17 00:00:00 2001
From: Fiona Corden <fiona.corden@ably.com>
Date: Fri, 9 Jan 2026 10:26:41 +0000
Subject: [PATCH 13/15] Fixup: further tweaks to intro text

---
 .../features/token-streaming/index.mdx        | 35 ++++++++++++++-----
 1 file changed, 27 insertions(+), 8 deletions(-)

diff --git a/src/pages/docs/ai-transport/features/token-streaming/index.mdx b/src/pages/docs/ai-transport/features/token-streaming/index.mdx
index 7deff6480d..77a56b9231 100644
--- a/src/pages/docs/ai-transport/features/token-streaming/index.mdx
+++ b/src/pages/docs/ai-transport/features/token-streaming/index.mdx
@@ -3,7 +3,20 @@ title: Token streaming
 meta_description: "Learn about token streaming with Ably AI Transport, including common patterns and the features provided by the Ably solution."
 ---
 
-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.
+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.
 
@@ -11,9 +24,14 @@ These failures frustrate users and waste compute resources. Every dropped stream
 
 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
+
 ![Ably AIT network diagram](../../../../../images/content/diagrams/ai-transport-before-and-after.png)
 
-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 or additional infrastructure.
+
+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 |
 |----------|----------------------|--------------------------|
@@ -22,6 +40,7 @@ Dropping in AI Transport to handle the token stream completely changes the user'
 | Browser crash | 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, thousands of 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.
 
@@ -42,9 +61,9 @@ This pattern is the recommended approach for most applications. It excels when:
 
 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.
+- 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
 
@@ -58,9 +77,9 @@ This pattern is useful when:
 
 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.
+- 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
 

From 1787502af6c1480b0dbff3df2995e89557c03e64 Mon Sep 17 00:00:00 2001
From: Fiona Corden <fiona.corden@ably.com>
Date: Fri, 9 Jan 2026 10:30:19 +0000
Subject: [PATCH 14/15] Manually fix up files that went wonky in rebase

---
 content/partials/types/_message.textile       | 131 ------------------
 .../token-streaming/message-per-response.mdx  |   4 +-
 2 files changed, 2 insertions(+), 133 deletions(-)
 delete mode 100644 content/partials/types/_message.textile

diff --git a/content/partials/types/_message.textile b/content/partials/types/_message.textile
deleted file mode 100644
index 272d7b8b28..0000000000
--- a/content/partials/types/_message.textile
+++ /dev/null
@@ -1,131 +0,0 @@
-A @Message@ represents an individual message that is sent to or received from Ably.
-
-h6(#name).
-  default: name
-  csharp: Name
-
-The event name, if provided. <br>__Type: @String@__
-
-h6(#data).
-  default: data
-  csharp: Data
-
-The message payload, if provided.<br>__Type: <span lang="default">@String@, @StringBuffer@, @JSON Object@</span><span lang="java">@String@, @ByteArray@, @JSONObject@, @JSONArray@</span><span lang="csharp">@String@, @byte[]@, @plain C# object that can be serialized to JSON@</span><span lang="ruby">@String@, @Binary@ (ASCII-8BIT String), @Hash@, @Array@</span><span lang="python">@String@, @Bytearray@, @Dict@, @List@</span><span lang="php">@String@, @Binary String@, @Associative Array@, @Array@</span><span lang="objc">@NSString *@, @NSData *@, @NSDictionary *@, @NSArray *@</span><span lang="swift">@String@, @NSData@, @Dictionary@, @Array@</span><span lang="flutter">@String@, @Map@, @List@</span>__
-
-h6(#extras).
-  default: extras
-  csharp: Extras
-
-Metadata and/or ancillary payloads, if provided. Valid payloads include "@push@":/docs/push/publish#payload, "@headers@" (a map of strings to strings for arbitrary customer-supplied metadata), "@ephemeral@":/docs/pub-sub/advanced#ephemeral, and "@privileged@":/docs/platform/integrations/webhooks#skipping objects.<br>__Type: <span lang="java">@JSONObject@, @JSONArray@</span><span lang="csharp">plain C# object that can be converted to JSON</span><span lang="jsall">@JSON Object@</span><span lang="ruby">@Hash@, @Array@</span><span lang="python">@Dict@, @List@</span><span lang="swift">@Dictionary@, @Array@</span><span lang="objc">@NSDictionary *@, @NSArray *@</span><span lang="php">@Associative Array@, @Array@</span>__
-
-h6(#id).
-  default: id
-  csharp: Id
-
-A Unique ID assigned by Ably to this message.<br>__Type: @String@__
-
-h6(#client-id).
-  default: clientId
-  csharp: ClientId
-  ruby: client_id
-  python: client_id
-
-The client ID of the publisher of this message.<br>__Type: @String@__
-
-h6(#connection-id).
-  default: connectionId
-  csharp: ConnectionId
-  ruby: connection_id
-  python: connection_id
-
-The connection ID of the publisher of this message.<br>__Type: @String@__
-
-h6(#connection-key).
-  default: connectionKey
-  csharp,go: ConnectionKey
-  ruby,python: connection_key
-
-A connection key, which can optionally be included for a REST publish as part of the "publishing on behalf of a realtime client functionality":/docs/pub-sub/advanced#publish-on-behalf.<br>__Type: @String@__
-
-h6(#timestamp).
-  default: timestamp
-  csharp: Timestamp
-
-Timestamp when the message was first received by the Ably, as <span lang="default">milliseconds since the epoch</span><span lang="ruby">a @Time@ object</span><br>.__Type: <span lang="default">@Integer@</span><span lang="java">@Long Integer@</span><span lang="csharp">@DateTimeOffset@</span><span lang="ruby">@Time@</span><span lang="objc,swift">@NSDate@</span>__
-
-h6(#encoding).
-  default: encoding
-  csharp: Encoding
-
-This will typically be 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 will contain the remaining transformations not applied to the @data@ payload.<br>__Type: @String@__
-
-blang[jsall].
-
-  h6(#action).
-    default: action
-
-  The action type of the message, one of the "@MessageAction@":#message-action enum values.<br>__Type: @int enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY }@__
-
-  h6(#serial).
-    default: 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, deletes, and appends in "channel rules":/docs/channels#rules .<br>__Type: @String@__
-
-  h6(#annotations).
-    default: annotations
-
-  An object containing information about annotations that have been made to the object.<br>__Type: "@MessageAnnotations@":/docs/api/realtime-sdk/types#message-annotations__
-
-  h6(#version).
-    default: version
-
-  An object containing version metadata for messages that have been updated or deleted. See "updating and deleting messages":/docs/messages/updates-deletes for more information.<br>__Type: "@MessageVersion@":#message-version__
-
-h3(constructors).
-  default: Message constructors
-
-h6(#message-from-encoded).
-  default: Message.fromEncoded
-
-bq(definition).
-  default: Message.fromEncoded(Object encodedMsg, ChannelOptions channelOptions?) -> Message
-
-A static factory method to create a "@Message@":/docs/api/realtime-sdk/types#message from a deserialized @Message@-like object encoded using Ably's wire protocol.
-
-h4. Parameters
-
-- encodedMsg := a @Message@-like deserialized object.<br>__Type: @Object@__
-- channelOptions := an optional "@ChannelOptions@":/docs/api/realtime-sdk/types#channel-options. If you have an encrypted channel, use this to allow the library can decrypt the data.<br>__Type: @Object@__
-
-h4. Returns
-
-A "@Message@":/docs/api/realtime-sdk/types#message object
-
-h6(#message-from-encoded-array).
-  default: Message.fromEncodedArray
-
-bq(definition).
-  default: Message.fromEncodedArray(Object[] encodedMsgs, ChannelOptions channelOptions?) -> Message[]
-
-A static factory method to create an array of "@Messages@":/docs/api/realtime-sdk/types#message from an array of deserialized @Message@-like object encoded using Ably's wire protocol.
-
-h4. Parameters
-
-- encodedMsgs := an array of @Message@-like deserialized objects.<br>__Type: @Array@__
-- channelOptions := an optional "@ChannelOptions@":/docs/api/realtime-sdk/types#channel-options. If you have an encrypted channel, use this to allow the library can decrypt the data.<br>__Type: @Object@__
-
-h4. Returns
-
-An @Array@ of "@Message@":/docs/api/realtime-sdk/types#message objects
-
-h3(#message-version).
-  default: MessageVersion
-
-h4. Properties
-
-|_. Property |_. Description |_. Type |
-| serial | An Ably-generated ID that uniquely identifies this version of the message. Can be compared lexicographically to determine version ordering. For an original message with an action of @message.create@, this will be equal to the top-level @serial@. | @String@ |
-| timestamp | The time this version was created (when the update or delete operation was performed). For an original message, this will be equal to the top-level @timestamp@. | <span lang="default">@Integer@</span><span lang="java">@Long Integer@</span><span lang="csharp">@DateTimeOffset@</span><span lang="ruby">@Time@</span><span lang="objc,swift">@NSDate@</span> |
-| clientId | The client identifier of the user who performed the update or delete operation. Only present for @message.update@ and @message.delete@ actions. | @String@ (optional) |
-| description | Optional description provided when the update or delete was performed. Only present for @message.update@ and @message.delete@ actions. | @String@ (optional) |
-| metadata | Optional metadata provided when the update or delete was performed. Only present for @message.update@ and @message.delete@ actions. | @Object@ (optional) |
diff --git a/src/pages/docs/ai-transport/features/token-streaming/message-per-response.mdx b/src/pages/docs/ai-transport/features/token-streaming/message-per-response.mdx
index 86f7787dc1..5718111f48 100644
--- a/src/pages/docs/ai-transport/features/token-streaming/message-per-response.mdx
+++ b/src/pages/docs/ai-transport/features/token-streaming/message-per-response.mdx
@@ -22,7 +22,7 @@ Standard Ably message [size limits](/docs/platform/pricing/limits#message) apply
 
 ## Enable appends <a id="enable"/>
 
-Message append functionality requires the "Message annotations, updates, deletes, and appends" [channel rule](/docs/channels#rules) enabled for your channel or [namespace](/docs/channels#namespaces).
+Message append functionality requires "Message annotations, updates, deletes and appends" to be enabled in a [channel rule](/docs/channels#rules) associated with the channel.
 
 <Aside data-type="important">
 When the "Message updates and deletes" channel rule is enabled, messages are persisted irrespective of whether or not persistence has also been explicitly enabled. This will be reflected in increased usage since [we charge for persisting messages](https://faqs.ably.com/how-does-ably-count-messages).
@@ -34,7 +34,7 @@ To enable the channel rule:
 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" rule from the list.
+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:*`.

From 8534f58e378d7a0b5c15af5374f114919c4e24aa Mon Sep 17 00:00:00 2001
From: Fiona Corden <fiona.corden@ably.com>
Date: Fri, 9 Jan 2026 10:31:03 +0000
Subject: [PATCH 15/15] Additional manual fix

---
 .../features/token-streaming/message-per-response.mdx           | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/pages/docs/ai-transport/features/token-streaming/message-per-response.mdx b/src/pages/docs/ai-transport/features/token-streaming/message-per-response.mdx
index 5718111f48..a501f562a6 100644
--- a/src/pages/docs/ai-transport/features/token-streaming/message-per-response.mdx
+++ b/src/pages/docs/ai-transport/features/token-streaming/message-per-response.mdx
@@ -34,7 +34,7 @@ To enable the channel rule:
 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.
+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:*`.