--- title: Building an adapter description: Learn how to build your own Chat SDK adapter for any messaging platform. docs_index: /llms.txt lastUpdated: 2026-10-14 type: guide prerequisites: - /docs/getting-started - /docs/adapters related: - /docs/contributing/testing - /docs/contributing/publishing - /docs/contributing/vendor-official - /docs/cards - /docs/actions --- > For an index of all documentation, see [/llms.txt](/llms.txt). Build your adapter as its own npm package. It implements the `Adapter` interface for your platform, converts messages between Chat SDK's Markdown AST and the platform's format, and exports a factory function such as `createMatrixAdapter`. ## What adapters are An adapter connects Chat SDK to one messaging platform. It handles webhook verification, message parsing, and API calls for that platform so your handler code stays platform-agnostic. Chat SDK ships with Vercel-maintained [official adapters](/adapters). Anyone can build an adapter for another platform with the same `Adapter` interface and publish it as a [community](/docs/contributing/publishing#listing-on-chat-sdkdev) or [vendor-official](/docs/contributing/vendor-official) adapter. ### Adapter tiers | Tier | Description | Examples | | --------------- | -------------------------------------------- | -------------------------- | | Official | Published under `@chat-adapter/*` by Vercel | Slack, Teams, Discord | | Vendor-official | Built and maintained by the platform company | Resend, Liveblocks, Photon | | Community | Built by third-party developers | Any open-source adapter | This guide covers the implementation. After you publish, [list a community adapter on chat-sdk.dev](/docs/contributing/publishing#listing-on-chat-sdkdev), or follow the [vendor-official guide](/docs/contributing/vendor-official) if you represent the platform vendor. > The `@chat-adapter/` npm scope is reserved for official adapters. Publish your adapter under your own scope or as an unscoped package. ## Project setup This guide uses a hypothetical Matrix adapter as a running example. Replace "matrix" with your platform name throughout. `YOUR_PUBLISHED_ADAPTER_PACKAGE` is a placeholder, not an npm package to install. Replace it with a valid package name you own before publishing. ### package.json ```json title="package.json" lineNumbers { "name": "YOUR_PUBLISHED_ADAPTER_PACKAGE", "version": "0.1.0", "description": "Matrix adapter for Chat SDK", "type": "module", "main": "./dist/index.js", "module": "./dist/index.js", "types": "./dist/index.d.ts", "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } }, "files": ["dist"], "scripts": { "build": "tsup", "dev": "tsup --watch", "test": "vitest run --coverage", "test:watch": "vitest", "typecheck": "tsc --noEmit", "clean": "rm -rf dist" }, "peerDependencies": { "chat": "^4.0.0" }, "dependencies": { "@chat-adapter/shared": "^4.0.0" }, "devDependencies": { "@types/node": "^22.0.0", "chat": "^4.0.0", "tsup": "^8.3.0", "typescript": "^5.7.0", "vitest": "^4.0.0" }, "publishConfig": { "access": "public" }, "keywords": ["chat-sdk", "chat-adapter", "matrix"], "license": "MIT" } ``` Key points: - The package is ESM-only (`"type": "module"`). - `chat` is a peer dependency because your adapter runs inside the consumer's `Chat` instance. - `@chat-adapter/shared` provides error classes and utility functions. ### tsup.config.ts ```typescript title="tsup.config.ts" lineNumbers import { defineConfig } from "tsup"; export default defineConfig({ entry: ["src/index.ts"], format: ["esm"], dts: true, clean: true, sourcemap: true, }); ``` ### tsconfig.json ```json title="tsconfig.json" lineNumbers { "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "bundler", "declaration": true, "outDir": "./dist", "rootDir": "./src", "strict": true, "strictNullChecks": true, "esModuleInterop": true, "skipLibCheck": true }, "include": ["src/**/*"], "exclude": ["node_modules", "dist", "**/*.test.ts"] } ``` ### vitest.config.ts ```typescript title="vitest.config.ts" lineNumbers import { defineProject } from "vitest/config"; export default defineProject({ test: { globals: true, environment: "node", coverage: { provider: "v8", reporter: ["text", "json-summary"], include: ["src/**/*.ts"], exclude: ["src/**/*.test.ts"], }, }, }); ``` ## Define your types Start by defining the platform-specific types your adapter needs. ```typescript title="src/types.ts" lineNumbers /** Decoded thread ID components for Matrix */ export interface MatrixThreadId { /** Matrix room ID (e.g., "!abc123:matrix.org") */ roomId: string; /** Matrix event ID for the thread root (e.g., "$event123") */ eventId?: string; } /** Configuration for the Matrix adapter */ export interface MatrixAdapterConfig { /** Matrix homeserver URL */ homeserverUrl: string; /** Access token for the bot account */ accessToken: string; /** Optional bot display name override */ userName?: string; } ``` Every adapter needs two interfaces: - A thread ID interface that describes the decoded components of your `{adapter}:{segment1}:{segment2}` thread ID. - A config interface for the credentials and options needed to connect to the platform. ## Implement the Adapter interface Create an adapter class that implements the `Adapter` interface from `chat`. Start with the class skeleton and constructor, then add each group of methods below. ```typescript title="src/adapter.ts" lineNumbers import { extractCard, extractFiles, toBuffer, ValidationError, } from "@chat-adapter/shared"; import type { Adapter, AdapterPostableMessage, ChatInstance, EmojiValue, FetchOptions, FetchResult, FormattedContent, Logger, RawMessage, ThreadInfo, WebhookOptions, } from "chat"; import { ConsoleLogger, Message } from "chat"; import { MatrixFormatConverter } from "./format-converter"; import type { MatrixAdapterConfig, MatrixThreadId } from "./types"; export class MatrixAdapter implements Adapter { readonly name = "matrix"; readonly userName: string; readonly botUserId?: string; private chat: ChatInstance | null = null; private logger: Logger; private config: MatrixAdapterConfig; private converter = new MatrixFormatConverter(); constructor(config: MatrixAdapterConfig & { logger?: Logger }) { this.config = config; this.userName = config.userName ?? "matrix-bot"; this.logger = config.logger ?? new ConsoleLogger(); } // Methods shown in sections below... } ``` The `Adapter` interface takes two generics: `TThreadId` (your decoded thread ID shape) and `TRawMessage` (the platform's raw message type). ### Initialization The SDK calls `initialize` once when the `Chat` instance is created. Use it to store the `ChatInstance` reference, set up your logger, validate credentials, and fetch bot info. ```typescript title="src/adapter.ts" async initialize(chat: ChatInstance): Promise { this.chat = chat; this.logger = chat.getLogger("matrix"); // Validate credentials, fetch bot user info, etc. // Example: const me = await this.apiCall("/account/whoami"); // this.botUserId = me.user_id; } ``` ### Disconnect The optional `disconnect()` method is called during `chat.shutdown()` to clean up resources. Use it to close persistent connections, tear down subscriptions, or release any platform-specific resources. ```typescript title="src/adapter.ts" async disconnect(): Promise { // Close WebSocket connections, clean up subscriptions, etc. // Example: await this.matrixClient.stop(); } ``` Adapters that don't hold persistent connections can skip this method entirely. ### Thread ID encode/decode Thread IDs typically follow the pattern `{adapter}:{segment1}:{segment2}`, though some adapters use more or fewer segments. The `encodeThreadId` and `decodeThreadId` methods must roundtrip consistently. Use `base64url` encoding for segments that contain special characters. `channelIdFromThreadId` returns the channel portion of a thread ID, which the SDK uses for channel-level operations such as `thread.channel`. ```typescript title="src/adapter.ts" lineNumbers encodeThreadId(data: MatrixThreadId): string { const roomSegment = Buffer.from(data.roomId).toString("base64url"); if (data.eventId) { const eventSegment = Buffer.from(data.eventId).toString("base64url"); return `matrix:${roomSegment}:${eventSegment}`; } return `matrix:${roomSegment}`; } decodeThreadId(threadId: string): MatrixThreadId { const parts = threadId.split(":"); if (parts.length < 2 || parts[0] !== "matrix") { throw new ValidationError(`Invalid Matrix thread ID: ${threadId}`); } const roomId = Buffer.from(parts[1], "base64url").toString(); const eventId = parts[2] ? Buffer.from(parts[2], "base64url").toString() : undefined; return { roomId, eventId }; } channelIdFromThreadId(threadId: string): string { const [adapter, roomSegment] = threadId.split(":"); return `${adapter}:${roomSegment}`; } ``` ### Webhook handling `handleWebhook` is the entry point for all incoming platform events. Always: 1. Verify the request signature first, and return 401 if it's invalid. 2. Parse the platform payload. 3. Call `this.chat.processMessage()` with positional args. It handles `waitUntil` internally. 4. Return a 200 response immediately. Polling transports should await the promises returned by `processMessage`, `processAction`, `processSlashCommand` and `processReaction` before acknowledging input. These promises reject on handler failure; the default `waitUntil` task still logs and absorbs errors for webhook responses. A transport that owns deduplication and recovery, such as Telegram polling, can pass `{ deduplicate: false }` to `processMessage` to bypass the core message deduplication cache. Leave deduplication enabled for ordinary webhook delivery. ```typescript title="src/adapter.ts" lineNumbers async handleWebhook( request: Request, options?: WebhookOptions ): Promise { // 1. Verify request signature const signature = request.headers.get("x-matrix-signature"); if (!signature) { return new Response("Missing signature", { status: 401 }); } const body = await request.text(); const isValid = this.verifySignature(body, signature); if (!isValid) { return new Response("Invalid signature", { status: 401 }); } // 2. Parse the webhook payload const payload = JSON.parse(body); // 3. Process the message asynchronously if (this.chat && payload.type === "m.room.message") { const threadId = this.encodeThreadId({ roomId: payload.room_id, eventId: payload.thread_root_id, }); // Use a factory function for lazy async parsing const isMention = this.checkMention(payload); const factory = async (): Promise> => { const msg = this.parseMessage(payload); if (isMention) { msg.isMention = true; } return msg; }; // processMessage handles waitUntil registration internally this.chat.processMessage(this, threadId, factory, options); } // 4. Return a fast 200 to acknowledge receipt return new Response("OK", { status: 200 }); } ``` ### Message parsing Convert the raw platform message into a normalized `Message` instance. The `author` fields use `userId` and `userName`, and `isBot` accepts `boolean | "unknown"`. Include a `metadata` object with `dateSent` and `edited` instead of a top-level `createdAt`. Set `author.isMe` only when the message was sent by this adapter runtime and should be ignored by Chat SDK's handler dispatch. Do not map a platform "sent from my account" flag directly to `isMe` unless that account is the bot identity. For user-owned account adapters, keep user-authored messages as `isMe: false` and track message IDs returned by `postMessage`; if the platform echoes one of those IDs through the webhook, mark that echo as `isMe: true` and `isBot: true`. Set `isMention` only when the adapter can decide it from the platform's own metadata. Chat SDK uses the value as the mention decision: `true` and `false` are final, and only `undefined` makes it fall back to matching `@username` in `text`. Leave the field unset when the adapter has no mention information instead of reporting `false`. The one exception is direct messages: when no `onDirectMessage` handler is registered, Chat SDK marks every DM as a mention regardless of what the adapter reported. ```typescript title="src/adapter.ts" lineNumbers parseMessage(raw: unknown): Message { const payload = raw as Record; return new Message({ id: payload.event_id as string, threadId: this.encodeThreadId({ roomId: payload.room_id as string, eventId: payload.thread_root_id as string | undefined, }), text: payload.body as string, formatted: this.converter.toAst(payload.body as string), raw, author: { userId: payload.sender as string, userName: payload.sender as string, fullName: payload.sender_display_name as string ?? "", isBot: (payload.sender as string).startsWith("@bot"), isMe: false, }, metadata: { dateSent: new Date(payload.origin_server_ts as number), edited: false, }, attachments: [], }); } ``` ### Sending messages Use `extractCard()` and `extractFiles()` from `@chat-adapter/shared` to check for rich content. Use `extractPostableAttachments()` if your adapter maps normalized `Attachment` objects to platform-native media uploads. Use your format converter's `renderPostable()` to convert the message to platform format. ```typescript title="src/adapter.ts" lineNumbers async postMessage( threadId: string, message: AdapterPostableMessage ): Promise> { const { roomId, eventId } = this.decodeThreadId(threadId); const card = extractCard(message); const files = extractFiles(message); // Upload files if present for (const file of files) { const buffer = await toBuffer(file.data); // Upload to Matrix media repo... } // Render text content const text = card ? this.converter.renderPostable({ card: message.card }) : this.converter.renderPostable(message); const response = await this.sendMatrixMessage(roomId, text, eventId); return { raw: response, id: response.event_id }; } async editMessage( threadId: string, messageId: string, message: AdapterPostableMessage ): Promise> { const { roomId } = this.decodeThreadId(threadId); const text = this.converter.renderPostable(message); const response = await this.editMatrixMessage(roomId, messageId, text); return { raw: response, id: response.event_id }; } async deleteMessage(threadId: string, messageId: string): Promise { const { roomId } = this.decodeThreadId(threadId); await this.redactMatrixEvent(roomId, messageId); } ``` ### Buttons and callback URLs When the host app passes a `Card` with `