ably · JoaoDiasAbly · Dec 2, 2025 · Dec 15, 2025 · Dec 15, 2025 · Dec 9, 2025
diff --git a/examples/ai-transport-message-per-token/javascript/README.md b/examples/ai-transport-message-per-token/javascript/README.md
@@ -0,0 +1,60 @@
+# AI Transport message per token streaming
+
+Enable realtime streaming of AI/LLM responses by publishing tokens as they arrive from Large Language Model services.
+
+AI Transport token streaming allows applications to provide immediate, responsive AI interactions by streaming tokens in realtime rather than waiting for complete responses. This pattern is essential for creating engaging AI-powered experiences where users can see responses being generated as they happen.
+
+The streaming approach significantly improves perceived performance and user engagement. Instead of waiting 5-10 seconds for a complete AI response, users see tokens appearing progressively, creating a more natural conversation flow similar to watching someone type in realtime.
+
+Token streaming is implemented using [Ably AI Transport](/docs/ai-transport). AI Transport provides purpose-built APIs for realtime AI applications, offering reliable message delivery, automatic ordering, and seamless reconnection handling to ensure no tokens are lost during network interruptions.
+
+## Resources
+
+Use the following methods to implement AI Transport token streaming:
+
+- [`client.channels.get()`](/docs/channels#create): creates a new or retrieves an existing channel for AI Transport token streaming.
+- [`channel.subscribe()`](/docs/channels#subscribe): subscribes to token messages from AI services by registering a listener for realtime streaming.
+- [`channel.publish()`](/docs/channels#publish): publishes individual tokens as they arrive from the LLM service with response tracking headers.
+- [`channel.history()`](/docs/channels/history) with [`untilAttach`](/docs/channels/options#attach): enables seamless message recovery during reconnections, ensuring no tokens are lost.
+
+Find out more about [AI Transport](/docs/ai-transport) and [message history](/docs/channels/history).
+
+## Getting started
+
+1. Clone the [Ably docs](https://github.com/ably/docs) repository where this example can be found:
+
+  ```sh
+  git clone git@github.com:ably/docs.git
+  ```
+
+2. Change directory:
+
+  ```sh
+  cd examples/
+  ```
+
+3. Rename the environment file:
+
+  ```sh
+  mv .env.example .env.local
+  ```
+
+4. In `.env.local` update the value of `VITE_ABLY_KEY` to be your Ably API key.
+
+5. Install dependencies:
+
+  ```sh
+  yarn install
+  ```
+
+6. Run the server:
+
+  ```sh
+  yarn run ai-transport-message-per-token-javascript
+  ```
+
+7. Try it out by opening [http://localhost:5173/](http://localhost:5173/) with your browser and selecting a prompt to see realtime AI token streaming.
+
+## Open in CodeSandbox
+
+In CodeSandbox, rename the `.env.example` file to `.env.local` and update the value of your `VITE_ABLY_KEY` variable to use your Ably API key.
diff --git a/examples/ai-transport-message-per-token/javascript/index.html b/examples/ai-transport-message-per-token/javascript/index.html
@@ -0,0 +1,46 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="stylesheet" href="src/styles.css" />
+    <title>AI Transport Token Streaming - JavaScript</title>
+  </head>
+
+  <body class="bg-gray-100">
+    <div class="max-w-6xl mx-auto p-5">
+      <!-- Response section with always visible status -->
+      <div class="mb-4">
+        <div class="flex-1">
+          <div class="text-sm text-gray-600 mt-4 mb-2 flex justify-between">
+            <span id="prompt-display"></span>
+            <div class="flex items-center gap-2">
+              <span class="text-xs bg-gray-200 px-2 py-1 rounded flex items-center gap-1">
+                <span id="processing-status">ready</span>
+              </span>
+              <!-- Disconnect/Reconnect button -->
+              <button id="connection-toggle" class="text-xs bg-blue-500 text-white px-2 py-1 rounded hover:bg-blue-600">
+                Disconnect
+              </button>
+            </div>
+          </div>
+          <div class="p-4 border border-gray-300 rounded-lg bg-gray-50 h-48 overflow-y-auto text-base leading-relaxed">
+            <span id="response-text">Select a prompt below to get started</span>
+            <span id="cursor" class="text-blue-600"></span>
+          </div>
+        </div>
+      </div>
+
+      <!-- Prompt selection -->
+      <div class="mb-4">
+        <div class="flex flex-wrap gap-2" id="prompt-buttons">
+          <button id="prompt-button" class="px-3 py-2 text-sm border rounded-md transition-colors">
+            What is Ably AI Transport?
+          </button>
+        </div>
+      </div>
+    </div>
+
+    <script type="module" src="src/script.ts"></script>
+  </body>
+</html>
diff --git a/examples/ai-transport-message-per-token/javascript/package.json b/examples/ai-transport-message-per-token/javascript/package.json
@@ -0,0 +1,10 @@
+{
+  "name": "ai-transport-message-per-token-javascript",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  }
+}
diff --git a/examples/ai-transport-message-per-token/javascript/src/agent.ts b/examples/ai-transport-message-per-token/javascript/src/agent.ts
@@ -0,0 +1,63 @@
+// Agent Service
+// This consumes LLM streams and publishes events to Ably
+
+import * as Ably from 'ably';
+import { MockLLM } from './llm';
+
+export class Agent {
+  private client: Ably.Realtime;
+  private channel: Ably.RealtimeChannel;
+  private llm: MockLLM;
+
+  constructor(ablyKey: string, channelName: string) {
+    this.client = new Ably.Realtime({
+      key: ablyKey,
+      clientId: 'ai-agent',
+    });
+    this.channel = this.client.channels.get(channelName);
+    this.llm = new MockLLM();
+  }
+
+  async processPrompt(prompt: string, responseId: string): Promise<void> {
+    const stream = await this.llm.responses.create(prompt);
+
+    for await (const event of stream) {
+      if (event.type === 'message_start') {
+        // Publish response start
+        this.channel.publish({
+          name: 'start',
+          data: {},
+          extras: {
+            headers: {
+              responseId,
+            },
+          },
+        });
+      } else if (event.type === 'message_delta') {
+        // Publish tokens
+        this.channel.publish({
+          name: 'token',
+          data: {
+            token: event.text,
+          },
+          extras: {
+            headers: {
+              responseId,
+            },
+          },
+        });
+      } else if (event.type === 'message_stop') {
+        // Publish response stop
+        this.channel.publish({
+          name: 'stop',
+          data: {},
+          extras: {
+            headers: {
+              responseId,
+            },
+          },
+        });
+      }
+    }
+  }
+}
diff --git a/examples/ai-transport-message-per-token/javascript/src/config.ts b/examples/ai-transport-message-per-token/javascript/src/config.ts
@@ -0,0 +1,3 @@
+export const config = {
+  ABLY_KEY: import.meta.env.VITE_ABLY_KEY || 'YOUR_ABLY_KEY_HERE',
+};
diff --git a/examples/ai-transport-message-per-token/javascript/src/llm.ts b/examples/ai-transport-message-per-token/javascript/src/llm.ts
@@ -0,0 +1,49 @@
+// Mock LLM Service
+// This simulates a generic LLM SDK with streaming capabilities
+
+interface StreamEvent {
+  type: 'message_start' | 'message_delta' | 'message_stop';
+  text?: string;
+  responseId: string;
+}
+
+export class MockLLM {
+  private readonly responseText =
+    'Ably AI Transport is a solution for building stateful, steerable, multi-device AI experiences into new or existing applications. You can use AI Transport as the transport layer with any LLM or agent framework, without rebuilding your existing stack or being locked to a particular vendor.';
+
+  responses = {
+    create: (prompt: string) => this.createStream(prompt),
+  };
+
+  private async *createStream(_prompt: string): AsyncIterable<StreamEvent> {
+    const responseId = `resp_${crypto.randomUUID()}`;
+
+    // Yield start event
+    yield { type: 'message_start', responseId };
+
+    // Chunk text into tokens (simulates LLM tokenization)
+    const tokens = this.chunkTextLikeAI(this.responseText);
+
+    for (const token of tokens) {
+      // Simulate realistic delay between tokens
+      await new Promise((resolve) => setTimeout(resolve, Math.random() * 150 + 50));
+
+      // Yield token event
+      yield { type: 'message_delta', text: token, responseId };
+    }
+
+    // Yield stop event
+    yield { type: 'message_stop', responseId };
+  }
+
+  private chunkTextLikeAI(text: string): string[] {
+    const chunks: string[] = [];
+    let pos = 0;
+    while (pos < text.length) {
+      const size = Math.floor(Math.random() * 8) + 1;
+      chunks.push(text.slice(pos, pos + size));
+      pos += size;
+    }
+    return chunks.filter((chunk) => chunk.length > 0);
+  }
+}
diff --git a/examples/ai-transport-message-per-token/javascript/src/script.ts b/examples/ai-transport-message-per-token/javascript/src/script.ts
@@ -0,0 +1,123 @@
+import * as Ably from 'ably';
+import { Agent } from './agent';
+import { config } from './config';
+
+// Generate unique channel name for this session
+const CHANNEL_NAME = `ai-transport-${crypto.randomUUID()}`;
+const client = new Ably.Realtime({
+  key: config.ABLY_KEY,
+});
+const channel = client.channels.get(CHANNEL_NAME);
+const responseTextElement = document.getElementById('response-text') as HTMLDivElement;
+const connectionToggle = document.getElementById('connection-toggle') as HTMLButtonElement;
+const promptButton = document.getElementById('prompt-button') as HTMLButtonElement;
+const processingStatus = document.getElementById('processing-status') as HTMLSpanElement;
+
+let currentResponseId: string | null = null;
+let responseCompleted = false;
+let responseText = '';
+let isHydrating = false;
+let pendingTokens: string[] = [];
+
+const updateDisplay = () => {
+  responseTextElement.innerText = responseText;
+  processingStatus.innerText = responseCompleted ? 'Completed' : 'In Progress';
+};
+
+channel.subscribe('start', (message) => {
+  const responseId = message.extras?.headers?.responseId;
+  if (responseId && currentResponseId === responseId) {
+    responseCompleted = false;
+    responseText = '';
+    pendingTokens = [];
+    updateDisplay();
+  }
+});
+
+channel.subscribe('token', (message) => {
+  const responseId = message.extras?.headers?.responseId;
+  if (responseId && currentResponseId === responseId) {
+    if (isHydrating) {
+      pendingTokens.push(message.data.token);
+    } else {
+      responseText += message.data.token;
+      updateDisplay();
+    }
+  }
+});
+
+channel.subscribe('stop', (message) => {
+  const responseId = message.extras?.headers?.responseId;
+  if (responseId && currentResponseId === responseId) {
+    responseCompleted = true;
+    updateDisplay();
+  }
+});
+
+// Hydrate from history after reattaching
+const hydrateFromHistory = async () => {
+  if (!currentResponseId) {
+    isHydrating = false;
+    return;
+  }
+
+  let page = await channel.history({ untilAttach: true });
+
+  const historyTokens: string[] = [];
+  while (page) {
+    for (const message of page.items) {
+      const responseId = message.extras?.headers?.responseId;
+      if (responseId !== currentResponseId) {
+        continue;
+      }
+      if (message.name === 'token') {
+        historyTokens.push(message.data.token);
+      } else if (message.name === 'stop') {
+        responseCompleted = true;
+      }
+    }
+    page = page.hasNext() ? await page.next() : null;
+  }
+
+  // History arrives newest-first, so reverse it
+  // Then append any tokens that arrived during hydration
+  responseText = historyTokens.reverse().join('') + pendingTokens.join('');
+  isHydrating = false;
+  updateDisplay();
+};
+
+const handlePromptClick = () => {
+  currentResponseId = `request-${crypto.randomUUID()}`;
+  responseText = '';
+  updateDisplay();
+  const agent = new Agent(config.ABLY_KEY, CHANNEL_NAME);
+  agent.processPrompt('What is Ably AI Transport?', currentResponseId);
+};
+
+const handleConnect = async () => {
+  // Set hydrating before attach to buffer any live tokens
+  isHydrating = true;
+  pendingTokens = [];
+
+  await channel.attach();
+  await hydrateFromHistory();
+
+  connectionToggle.innerText = 'Disconnect';
+};
+
+const handleDisconnect = async () => {
+  await channel.detach();
+  processingStatus.innerText = 'Paused';
+  connectionToggle.innerText = 'Connect';
+};
+
+const handleConnectionToggle = () => {
+  if (channel.state === 'attached') {
+    handleDisconnect();
+  } else {
+    handleConnect();
+  }
+};
+
+connectionToggle.onclick = handleConnectionToggle;
+promptButton.onclick = handlePromptClick;
diff --git a/examples/ai-transport-message-per-token/javascript/src/styles.css b/examples/ai-transport-message-per-token/javascript/src/styles.css
@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
diff --git a/examples/ai-transport-message-per-token/javascript/tailwind.config.ts b/examples/ai-transport-message-per-token/javascript/tailwind.config.ts
@@ -0,0 +1,9 @@
+import baseConfig from '../../tailwind.config';
+import type { Config } from 'tailwindcss';
+
+const config: Config = {
+  ...baseConfig,
+  content: ['./src/**/*.{js,ts,tsx}', './index.html'],
+};
+
+export default config;
diff --git a/examples/ai-transport-message-per-token/javascript/vite.config.ts b/examples/ai-transport-message-per-token/javascript/vite.config.ts
@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite';
+import baseConfig from '../../vite.config';
+
+export default defineConfig({
+  ...baseConfig,
+  envDir: '../../',
+});