vercel__chat/apps/docs/content/adapters/official/web.mdx

---
title: Web
description: Web chat adapter that speaks the AI SDK useChat protocol.
packageName: "@chat-adapter/web"
slug: web
type: platform
logo: web
tagline: Lets a Chat SDK bot serve a browser chat UI alongside Slack, Teams, Discord — the same handler fires for every platform. Speaks the AI SDK UI message stream protocol so @ai-sdk/react's useChat and ai-elements work out of the box.
beta: true
features:
  postMessage: yes
  editMessage: no
  deleteMessage: no
  fileUploads: no
  streaming:
    status: yes
    label: Native (SSE)
  scheduledMessages: no
  cardFormat:
    status: partial
    label: Markdown only (v1)
  buttons: no
  linkButtons: no
  selectMenus: no
  tables:
    status: yes
    label: GFM
  fields: no
  imagesInCards: no
  modals: no
  slashCommands: no
  mentions: no
  addReactions: no
  removeReactions: no
  typingIndicator: no
  directMessages: yes
  ephemeralMessages: no
  customApiEndpoint: yes
  fetchMessages:
    status: partial
    label: State cache
  fetchThreadInfo:
    status: yes
    label: Synthesized
  fetchChannelMessages:
    status: partial
    label: State cache
  listThreads: no
  postChannelMessage: no
---

## Install

<PackageInstall package="@chat-adapter/web ai @ai-sdk/react" />

## Quick start

```typescript title="lib/bot.ts" lineNumbers
import { Chat } from "chat";
import { createWebAdapter } from "@chat-adapter/web";
import { createMemoryState } from "@chat-adapter/state-memory";

export const bot = new Chat({
  userName: "mybot",
  adapters: {
    web: createWebAdapter({
      userName: "mybot",
      getUser: (req) => ({ id: getUserIdFromCookie(req) }),
    }),
  },
  state: createMemoryState(),
});

bot.onDirectMessage(async (thread, message) => {
  await thread.post(`You said: ${message.text}`);
});
```

```typescript title="app/api/chat/route.ts" lineNumbers
import { after } from "next/server";
import { bot } from "@/lib/bot";

export async function POST(request: Request): Promise<Response> {
  return bot.webhooks.web(request, {
    waitUntil: (task) => after(() => task),
  });
}
```

```tsx title="app/chat/page.tsx" lineNumbers
"use client";
import { useChat } from "@chat-adapter/web/react";

export default function ChatPage() {
  const { messages, sendMessage, status, stop } = useChat();
  // Render with `ai-elements` (<Conversation>, <Message>, <PromptInput>)
  // or your own components — `messages`, `sendMessage`, `status` are the
  // standard `@ai-sdk/react` API.
}
```

## Configuration

<TypeTable
  type={{
    userName: {
      type: "string",
      description:
        "Bot username. Required by Chat SDK for mention detection and to seed the bot identity for assistant messages.",
    },
    getUser: {
      type: "(request: Request) => WebUser | null | Promise<WebUser | null>",
      description:
        "Resolves the user from the inbound HTTP request. Returning `null` produces HTTP 401. This is the security boundary for the Web adapter.",
    },
    persistMessageHistory: {
      type: "boolean",
      default: "true",
      description:
        "Persist incoming message history in the configured state adapter. Set to `false` only if your handler re-derives history from the request body.",
    },
    threadIdFor: {
      type: "({ user, conversationId }) => string",
      description:
        "Override how thread ids are derived. Default: `web:{user.id}:{conversationId}`.",
    },
    logger: {
      type: "Logger",
      description: 'Defaults to `ConsoleLogger("info")`.',
    },
  }}
/>

## Authentication

`getUser` is the **security boundary** for the Web adapter. Unlike Slack or Teams where the platform signs every webhook, web requests come straight from a browser — you must identify the caller yourself.

```typescript title="lib/bot.ts" lineNumbers
// NextAuth
createWebAdapter({
  userName: "mybot",
  getUser: async (req) => {
    const session = await getServerSession(authOptions);
    if (!session?.user) return null;
    return { id: session.user.id, name: session.user.name };
  },
});

// Clerk
createWebAdapter({
  userName: "mybot",
  getUser: async () => {
    const { userId, sessionClaims } = await auth();
    if (!userId) return null;
    return { id: userId, name: sessionClaims?.name as string | undefined };
  },
});
```

The resolved `user.id` is embedded in the Chat SDK thread id. Ids containing `:` are rejected with HTTP 400 — normalize them inside `getUser` (e.g. base64-encode them) if your auth provider emits ids like `provider:sub`.

## Advanced

### Threading

By default, each `useChat` conversation maps to one Chat SDK thread:

```
web:{user.id}:{conversationId}
```

`conversationId` is the `id` field useChat sends in its request body. If your client supplies one (`useChat({ id: "support-chat" })`), it's reused across reloads; otherwise a fresh id is generated per request.

Override with `threadIdFor` if you want a single thread per user:

```typescript
createWebAdapter({
  userName: "mybot",
  getUser,
  threadIdFor: ({ user }) => `web:${user.id}:default`,
});
```

The encode/decode helpers are available on the adapter:

```typescript
adapter.encodeThreadId({ userId: "u1", conversationId: "abc" });
// → "web:u1:abc"
adapter.decodeThreadId("web:u1:abc");
// → { userId: "u1", conversationId: "abc" }
```

### Streaming

`thread.post` accepts an `AsyncIterable<string | StreamChunk>` and pumps deltas straight onto the SSE response — no edit loop, no rate limiting. Plays nicely with `streamText` from the AI SDK:

```typescript
import { streamText } from "ai";

bot.onDirectMessage(async (thread, message) => {
  const result = streamText({ model, prompt: message.text });
  await thread.post(result.textStream);
});
```

The adapter honors `request.signal`, so calling `stop()` from `useChat` short-circuits the iterator on the server.

### Message persistence

`persistMessageHistory` defaults to `true`. Web has no platform-side history API, so the only way for handlers to see prior turns via `thread.messages` is through the configured state adapter's cache. Set it to `false` only if your handler re-derives history from the request body's `messages[]`.

### React hook

`@chat-adapter/web/react` exports a thin wrapper around `@ai-sdk/react`'s `useChat` preconfigured with `DefaultChatTransport`:

```tsx
import { useChat } from "@chat-adapter/web/react";

const { messages, sendMessage, status, stop, regenerate } = useChat({
  api: "/api/chat",
  threadId: "support-1",
});
```

| Option | Description |
|--------|-------------|
| `api` | API endpoint for the Web adapter route. Defaults to `/api/chat`. |
| `threadId` | Chat SDK thread id — surfaces in the request body's `id`. Strongly recommended. |
| `experimental_throttle` | Throttle wait in ms for chat messages and data updates. |
| `resume` | Whether to resume an ongoing chat generation stream. |
| ...rest | All other options pass through to `@ai-sdk/react`'s `useChat`. |

For advanced configuration, use `@ai-sdk/react`'s `useChat` directly — there's nothing magical in the wrapper.

## Feature support

<FeatureSupport />