@liveblocks/chat-sdk-adapter

@liveblocks/chat-sdk-adapter is a Chat SDK platform adapter backed by Liveblocks Comments. It maps Liveblocks rooms, threads, and comments to the Chat SDK's Channel / Thread / Message model, allowing you to build conversational bots that read and post in Liveblocks comment threads.

Installation

Terminal

npm install @liveblocks/chat-sdk-adapter chat

Prerequisites

Before using this adapter, ensure you have:

A Liveblocks project with rooms using Comments.
A secret key (sk_...) from the Liveblocks dashboard for REST API calls.
A webhook secret (whsec_...) from the dashboard to verify webhook payloads.
Webhooks configured to subscribe to commentCreated, commentReactionAdded, and commentReactionRemoved events.
A stable botUserId that matches how you identify users in your app.

createLiveblocksAdapter

Factory function that creates a new LiveblocksAdapter instance.

import { createLiveblocksAdapter } from "@liveblocks/chat-sdk-adapter";
const adapter = createLiveblocksAdapter({  apiKey: "",  webhookSecret: "whsec_...",  botUserId: "my-bot-user",  botUserName: "MyBot",});

Configuration options

apiKeystringRequired
Liveblocks secret key (sk_...) for REST API calls.
webhookSecretstringRequired
Webhook secret (whsec_...) from the dashboard.
botUserIdstringRequired
User ID used when the bot creates, edits, or reacts to comments. Should match your app's user identifiers.
botUserNamestringDefault is "liveblocks-bot"
Display name for the bot.
resolveUsersfunction
Resolves user IDs to user info for mentions. Returns an array of user info in the same order as the input IDs, or undefined to skip resolution.
resolveGroupsInfofunction
Resolves group IDs to group info for mentions. Returns an array of group info in the same order as the input IDs, or undefined to skip resolution.
loggerLoggerDefault is ConsoleLogger('info')
Chat SDK-compatible logger instance.

Resolving mentions

When comments contain @mentions, the adapter needs to resolve user and group IDs to display names. Use resolveUsers and resolveGroupsInfo to provide this mapping:

const adapter = createLiveblocksAdapter({  apiKey: "",  webhookSecret: "whsec_...",  botUserId: "my-bot-user",
  resolveUsers: async ({ userIds }) => {    const users = await getUsersFromDatabase(userIds);    return users.map((user) => ({      name: user.fullName,      avatar: user.avatarUrl,    }));  },
  resolveGroupsInfo: async ({ groupIds }) => {    const groups = await getGroupsFromDatabase(groupIds);    return groups.map((group) => ({ name: group.displayName }));  },});

Webhook events

The adapter processes incoming Liveblocks webhook requests via the Chat SDK's webhook handler. Supported events:

commentCreated — Triggers message processing in the Chat SDK
commentReactionAdded — Triggers reaction handlers
commentReactionRemoved — Triggers reaction handlers

export async function POST(request: Request) {  return bot.webhooks.liveblocks(request, {    waitUntil: (p) => void p,  });}

Webhook verification

The adapter automatically verifies webhook signatures using the webhookSecret provided during configuration. Invalid requests receive a 401 response.

ID encoding

The adapter uses a prefixed encoding scheme for thread and channel IDs:

Thread ID: liveblocks:{roomId}:{threadId}
Channel ID: liveblocks:{roomId}

encodeThreadId

Encodes a Liveblocks room ID and thread ID into a single thread ID string.

adapter.encodeThreadId(data: { roomId: string; threadId: string }): string

const encoded = adapter.encodeThreadId({  roomId: "my-room",  threadId: "th_abc123",});// "liveblocks:my-room:th_abc123"

decodeThreadId

Decodes an encoded thread ID string back into its room ID and thread ID components. Throws an Error if the format is invalid.

adapter.decodeThreadId(threadId: string): { roomId: string; threadId: string }

const { roomId, threadId } = adapter.decodeThreadId(  "liveblocks:my-room:th_abc123");// roomId: "my-room"// threadId: "th_abc123"

Room IDs may contain colons (:), which are preserved during encoding/decoding. However, Liveblocks thread IDs must not contain colons as the last colon is used as the delimiter when decoding.

Liveblocks-specific behavior

Reactions

Liveblocks Comments only supports Unicode emoji. Custom emoji identifiers that cannot be resolved to Unicode will fail validation.

await adapter.addReaction(threadId, messageId, "👍"); // Worksawait adapter.addReaction(threadId, messageId, "thumbs_up"); // Converted to 👍

Typing indicators

The startTyping method is a no-op as typing indicators are not supported by Liveblocks Comments.

Message format limitations

Limited formatting support

Liveblocks Comments has a simpler content model than full Markdown. Content from the Chat SDK is automatically converted, but some formatting is flattened.

Liveblocks Comments supports:

Paragraphs with inline formatting (bold, italic, code, strikethrough)
Links
@mentions (users and groups)

The following are not supported and will be flattened to plain text:

Headings — Converted to paragraphs
Bullet and numbered lists — Converted to paragraphs
Code blocks — Converted to paragraphs
Tables — Converted to ASCII representation in a paragraph
HTML — Rendered as plain text

Card payloads from the Chat SDK are converted to markdown/plain text (or use fallbackText if provided), then converted to a comment body. Interactivity is not preserved.

Example

Here's a complete example integrating the adapter with the Chat SDK:

import { Chat } from "chat";import {  createLiveblocksAdapter,  LiveblocksAdapter,} from "@liveblocks/chat-sdk-adapter";import { createMemoryState } from "@chat-adapter/state-memory";
const bot = new Chat<{ liveblocks: LiveblocksAdapter }>({  userName: "MyBot",  adapters: {    liveblocks: createLiveblocksAdapter({      apiKey: "",      webhookSecret: "whsec_...",      botUserId: "my-bot-user",      botUserName: "MyBot",      resolveUsers: async ({ userIds }) => {        const users = await getUsersFromDatabase(userIds);        return users.map((user) => ({ name: user.fullName }));      },    }),  },  state: createMemoryState(),});
bot.onNewMention(async (thread, message) => {  await thread.adapter.addReaction(thread.id, message.id, "👀");  await thread.post(`Hello, ${message.author.userName}!`);});
bot.onReaction(async (event) => {  if (!event.added) return;  await event.adapter.postMessage(    event.threadId,    `${event.user.userName} reacted with "${event.emoji.name}"`  );});

Webhook handler (Next.js)

import { bot } from "./bot";
export async function POST(request: Request) {  return bot.webhooks.liveblocks(request, {    waitUntil: (p) => void p,  });}

The waitUntil option is recommended for serverless environments (e.g., Vercel) to allow background processing of messages after the response is sent.