Get started with a Chat SDK bot using Liveblocks and Next.js

Liveblocks is a realtime collaboration infrastructure for building performant collaborative experiences. Follow the following steps to start building a bot that reads and responds to Liveblocks comment threads using the Chat SDK and the @liveblocks/chat-sdk-adapter in your Next.js /app directory application.

Quickstart

1. Install Liveblocks and Chat SDK

   Install the Liveblocks Chat SDK adapter, the Chat SDK, and a state adapter.

   Terminal

   npm

   npm install @liveblocks/chat-sdk-adapter @liveblocks/node chat @chat-adapter/state-memory

2. Add your environment variables

   Create a new .env.local file and add your Liveblocks secret key and webhook secret from the dashboard.

   .env.local

   LIVEBLOCKS_SECRET_KEY="sk_prod_xxxxxxxxxx…xxxxxxxxsk_prod_xxxxxxxxxxxxxxxxxxxxxxxx"LIVEBLOCKS_WEBHOOK_SECRET="whsec_..."

   You'll create the webhook and get the secret in the final step.

3. Create a user database

   Create a file to store your bot's user ID and a function to resolve users. The resolveUsers function converts user IDs from mentions into display names.

   app/database.ts

   export const BOT_USER_ID = "__bot__";export const BOT_USER_NAME = "My Bot";
   // A mock database with example usersconst USER_INFO = [  {    id: "user-1",    info: {      name: "Charlie Layne",    },  },  {    id: "user-2",    info: {      name: "Mislav Abha",    },  },  {    id: BOT_USER_ID,    info: {      name: BOT_USER_NAME,    },  },];
   export function getUser(id: string) {  return USER_INFO.find((u) => u.id === id) || undefined;}

4. Create the bot instance

   Create a bot instance using the Chat SDK with the Liveblocks adapter. The adapter connects your bot to Liveblocks comment threads.

   app/bot.ts

   import { Chat } from "chat";import {  createLiveblocksAdapter,  LiveblocksAdapter,} from "@liveblocks/chat-sdk-adapter";import { createMemoryState } from "@chat-adapter/state-memory";import { BOT_USER_ID, BOT_USER_NAME, getUser } from "./database";
   export const bot = new Chat<{ liveblocks: LiveblocksAdapter }>({  userName: BOT_USER_NAME,  adapters: {    liveblocks: createLiveblocksAdapter({      apiKey: process.env.LIVEBLOCKS_SECRET_KEY!,      webhookSecret: process.env.LIVEBLOCKS_WEBHOOK_SECRET!,      botUserId: BOT_USER_ID,      botUserName: BOT_USER_NAME,      resolveUsers: ({ userIds }) => {        return userIds.map((id) => getUser(id)?.info);      },    }),  },  state: createMemoryState(),});

5. Handle mentions and reactions

   Add event handlers to respond when users mention the bot or react to messages. Add these handlers to your app/bot.ts file after the bot instance.

   app/bot.ts

   // Handle @-mentions of the botbot.onNewMention(async (thread, message) => {  // Add a reaction to acknowledge the message  await thread.adapter.addReaction(thread.id, message.id, "👀");
     // Reply in the thread  await thread.post(`Hello ${message.author.userName}! How can I help?`);});
   // Handle reactions to messagesbot.onReaction(async (event) => {  if (!event.added) return;
     await event.adapter.postMessage(    event.threadId,    `${event.user.userName} reacted with "${event.emoji.name}"`  );});

6. Create the webhook endpoint

   Create an API route to receive Liveblocks webhooks. The bot processes incoming comments and reactions through this endpoint.

   app/api/webhooks/liveblocks/route.ts

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

   For production deployments on Vercel, use waitUntil from @vercel/functions for background processing:

   app/api/webhooks/liveblocks/route.ts

   import { bot } from "@/app/bot";import { waitUntil } from "@vercel/functions";
   export async function POST(request: Request) {  return bot.webhooks.liveblocks(request, { waitUntil });}

7. Set up Liveblocks webhooks

   The final step is to configure Liveblocks webhooks to send events to your bot.

   1. Follow the guide on testing webhooks locally
   2. When creating the webhook endpoint in the dashboard, enable these events:
      • commentCreated
      • commentReactionAdded
      • commentReactionRemoved
   3. Copy your webhook secret (whsec_...) and add it to .env.local

   Now when users @-mention your bot or react to messages in comment threads, your bot will respond automatically.

   Set up webhooks

What to read next

Congratulations! You've set up a bot that responds to Liveblocks comment threads using the Chat SDK.

• Chat SDK documentation
• @liveblocks/chat-sdk-adapter README
• Webhooks documentation
• How to test webhooks on localhost

Examples using Chat SDK