Chat SDK: One Bot for Slack, Teams, WhatsApp, and Telegram

Chat SDK is Vercel's open-source TypeScript library for writing bot logic once and running it on Slack, Microsoft Teams, Google Chat, Discord, Telegram, WhatsApp, and more. This guide explains how it works, how it connects to an AI model, where platforms behave differently, and the mistakes that tend to show up in production.

Published 11 min read
Purple and blue chat bubbles on a soft, blurred background

A company that wants an assistant for its staff usually needs it in Slack or Microsoft Teams. The same company often wants a customer-facing bot on WhatsApp or Telegram as well. Each of these platforms has its own webhook format, its own way of drawing buttons, its own limits on editing messages, and its own rules on who can message whom. Building for two or three of them used to mean two or three separate codebases. Chat SDK, published by Vercel as the npm package chat, tries to put those differences behind a single interface. This guide looks at what it actually does, how it fits next to an AI model, and which details still differ from platform to platform, because some of them matter a great deal once real users arrive.

First, Which "Chat SDK"?

The name has been used for two different things, which confuses a lot of searches. Until early 2026, Chat SDK at chat-sdk.dev referred to Vercel's Next.js chatbot template, a ready-made web app that looks and behaves much like ChatGPT. In February 2026 Vercel open-sourced a new library under the same name as a public beta, and the template moved to its own site. If a tutorial describes Chat SDK as a web chat interface with a sidebar of conversations, it is talking about the template. This article covers the library.

It also helps to be clear about what the library is not. Chat SDK does not call language models. That is the job of the AI SDK, TanStack AI, or a provider's own client. Chat SDK handles the chat platform side: receiving messages, keeping track of conversations, and sending replies in a form each platform understands. The two are designed to work together, but they solve different problems.

How It Works

There are three parts. The Chat instance is the coordinator: it holds your handlers and routes incoming events to them. Adapters do the platform work, one package per platform, such as @chat-adapter/slack or @chat-adapter/whatsapp. The state adapter stores thread subscriptions, locks, and caches, usually in Redis or PostgreSQL.

When a webhook arrives, the adapter checks the request signature, turns the platform payload into a normalized message, and hands it to the Chat instance. Your handler replies with thread.post(), passing a plain string, markdown, a card, or a stream. The adapter then converts that reply into the native format: Block Kit on Slack, Adaptive Cards on Teams, Google Chat cards, inline keyboards on Telegram, and so on.

The handlers follow the shape of a conversation. onNewMention fires when someone mentions the bot in a thread it is not following yet. If the handler calls thread.subscribe(), later messages in that thread go to onSubscribedMessage instead. onDirectMessage handles private chats, onNewMessage takes a regular expression for keyword triggers, and there are separate handlers for reactions, button clicks (onAction), slash commands, and modal forms.

Supported Platforms

Adapters come in three tiers. Official adapters are maintained by Vercel and published under the @chat-adapter scope. Vendor-official adapters are maintained by the platform company itself. Community adapters are built by other developers and published under their own names.

TierExamples (as of version 4.45, November 2026)
Official (Vercel)Slack, Microsoft Teams, Google Chat, Discord, Telegram, WhatsApp Business Cloud, Messenger, Instagram, GitHub, GitLab, Linear, Notion, Gmail, Twilio, X, Twitch, and a Web adapter for your own site
Vendor-officialResend for email, Lark/Feishu, Liveblocks, Novu, Beeper Matrix, and several iMessage and SMS providers
CommunityLINE, Mattermost, Rocket.Chat, Webex, Zoom Team Chat, Signal, and unofficial WhatsApp adapters built on Baileys
StateMemory for development, Redis, ioredis (for Cluster or Sentinel), and PostgreSQL, plus community MySQL and Cloudflare Durable Objects

Vercel also publishes @chat-adapter/catalog, a small package that lists every adapter with its capabilities and required environment variables. It is the most reliable way to check what a given adapter supports, because the list changes quickly. The core package went from 4.0.0 in January 2026 to 4.45.0 in November, with a new minor release every week or two.

Same Code, Different Behavior

Writing a handler once does not mean every platform will show the same thing. Each adapter does what its platform allows, and the differences are large enough to affect how you design the conversation.

PlatformHow a streamed reply appearsWhat to keep in mind
SlackNative streaming: text appears as the model writes itThe most complete adapter, with modals, slash commands, ephemeral messages, and edit and delete events
Microsoft TeamsNative in direct messages, a single final message in group chatsModals work, slash commands do not, and reading history needs Microsoft Graph permissions
Google ChatThe bot posts a message, then edits it as text arrivesNo modals; reading history and opening DMs need extra Workspace delegation setup
DiscordPost first, then edit as chunks come inSlash commands and buttons arrive by webhook, but ordinary messages only arrive over the Gateway WebSocket
TelegramPost and edit, roughly one edit per second, with optional draft previews in private chatsSlash commands and inline keyboard buttons are supported; conversations are locked per chat by default
WhatsAppBuffered: the whole answer is sent as one message at the endUp to three reply buttons with 20-character labels, no editing or deleting, and the 24-hour messaging window
WebNative streaming over server-sent events to useChatLets the same bot serve a chat widget on your own site through the AI SDK UI packages

In practice, the safest approach is to design for the weakest channel you plan to support and add extras where they exist. A card with three buttons works on Slack, Teams, Telegram, and WhatsApp. A card with five buttons and a dropdown will look fine on Slack and quietly fall back to text on WhatsApp.

Setting Up a First Bot

  1. 1Start from the scaffolder: npm create chat-sdk@latest my-bot. It asks which adapters you want and generates a small Next.js app with only webhook routes: src/lib/bot.ts for the bot, app/api/webhooks/[platform]/route.ts for incoming events, and a .env.example listing the variables you need. Non-interactive use looks like npm create chat-sdk@latest -- my-bot --adapter slack redis -y.
  2. 2If you prefer to add it to an existing project, install the core and the adapters you need: npm i chat @chat-adapter/slack @chat-adapter/state-redis. The packages require Node.js 20 or newer.
  3. 3Create the bot with new Chat({ userName: 'mybot', adapters: { slack: createSlackAdapter() }, state: createRedisState() }). The factories read credentials from environment variables such as SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET, and REDIS_URL, so you only pass options when you want to override them.
  4. 4Register a handler, for example bot.onNewMention(async (thread) => { await thread.subscribe(); await thread.post('Hi, I am following this thread now.') }). Adding Teams or Google Chat later is a matter of adding another adapter to the same object; the handler stays the same.
  5. 5Expose the webhook. Each adapter gets a handler at bot.webhooks.slack, bot.webhooks.teams, and so on. In a Next.js route, return bot.webhooks.slack(request, { waitUntil: (task) => after(() => task) }) so the function stays alive while your handler finishes.
  6. 6Point the platform at that URL: the event subscription in the Slack app settings, the messaging endpoint in Azure Bot Service for Teams, or the callback URL in the Meta app for WhatsApp.

Connecting It to an AI Model

thread.post() accepts any async iterable of strings, so a model's output can go straight into the chat. With the AI SDK, which Chat SDK lists as an optional peer dependency in versions 6 and 7, you pass the stream from your agent directly: await thread.post(result.fullStream). Streams from TanStack AI are detected as well.

Use fullStream rather than textStream when the agent calls tools. textStream joins the text of every step without separators, so a reply can come out as "hello.how are you?". fullStream includes step boundaries, and Chat SDK uses them to insert paragraph breaks. It is also worth passing thread.signal to the model call. On Slack, when the user presses the stop button, the signal is aborted and generation stops instead of running to the end and costing tokens nobody will read.

For multi-turn conversations, toAiMessages() converts thread messages into the role and content format a model expects. If the same person talks to the bot on more than one platform, the History API (bot.history.user) can keep a single transcript per user, keyed by an identity resolver you write. It also has a delete call for "forget me" requests, which matters if you operate under GDPR or a similar data protection law.

Two small details make streamed replies look better. Partial markdown, such as an opening ** without its closing pair, is repaired in intermediate updates so the message does not flash broken formatting. Tables in model output are held back until the separator row arrives, so users do not see raw pipe characters for a moment.

Problems That Show Up in Production

  • Memory state outside development. The memory adapter keeps subscriptions and locks inside one process. On serverless, or with more than one server, instances do not share it, and a restart forgets every subscribed thread. Use Redis, ioredis, or PostgreSQL before going live.
  • Messages disappearing under the default concurrency setting. The default strategy is drop: if a message arrives while the handler for that thread is still running, the new message is discarded with a LockError. On WhatsApp and Telegram people often send "hi", then "quick question", then the actual question, a second apart. Set concurrency to debounce, which waits 1.5 seconds by default and keeps only the last message, or burst, which waits the same way but passes the earlier messages to your handler in context.skipped. queue is the better fit when every message matters.
  • Slow acknowledgement. Slack expects a webhook to be acknowledged within three seconds. AI replies take longer, so the work has to continue after the response is sent, which is what waitUntil is for. On a serverless platform, leaving it out can mean the function is stopped halfway through a reply.
  • Assuming a failed event will be retried. Chat SDK deduplicates webhooks for ten minutes by default, so if a handler fails and the platform redelivers the event, the second delivery may be skipped. Returning a 500 does not guarantee another attempt. For actions that must not be lost, such as creating an order, record the work somewhere durable before replying.
  • Discord on serverless. Slash commands and button clicks arrive by webhook, but normal messages and reactions only come through the Gateway WebSocket. The scaffolder adds a cron job that keeps that connection going every nine minutes, which needs a paid Vercel plan. Matrix and Lark adapters need a long-running process and are not offered by the scaffolder at all.
  • Expecting the same features everywhere. Modals work only on Slack and Teams. Edit and delete events are currently only emitted by the Slack adapter. Registering those handlers elsewhere does no harm, but nothing will call them.
  • Relying on adapter internals. Official adapters can be subclassed, but the protected members you override are documented as not yet stable and may change in minor releases. Pin the version if you do this, and read the changelog before upgrading.

Notes for WhatsApp Bots

The official WhatsApp adapter uses Meta's WhatsApp Business Cloud API, with credentials from a Meta app: an access token, the app secret, a phone number ID, and a verify token you choose for the webhook handshake. For production, use a permanent System User token instead of the temporary one shown on the setup page.

WhatsApp's own rules still apply. Outside the 24-hour customer service window, a business can only send pre-approved template messages, which the adapter sends through sendTemplate. Messages cannot be edited, so a streamed AI answer is collected and sent in one piece; calling thread.startTyping() shows a typing indicator for up to 25 seconds so the user knows something is happening. Long replies are split automatically at 4,096 characters.

The community adapters built on Baileys connect through the WhatsApp Web protocol instead of the official API. They are handy for experiments, but WhatsApp does not permit that kind of automation for business use, and the number can be banned. For anything customers rely on, stay with the Cloud API.

Approvals and Longer Workflows

A common request for internal bots is a step where a person has to approve something: a refund, a deployment, a purchase. requestApproval from chat/workflow posts a card with Approve and Deny buttons and pauses a Workflow SDK workflow until someone clicks. The wait can last minutes or days and survives deploys. The approvers option limits who can decide, and it should be set for anything with real consequences, because by default anyone who can see the card can click it. Once a decision is made, the card is edited to show who decided, which leaves a simple audit trail in the thread.

Running It Outside Vercel

Chat SDK is MIT-licensed and runs on any Node.js host. Webhook handlers can live in Next.js, Hono, Nuxt, SvelteKit, Express, or a similar framework. On a regular VPS with a long-running Node.js process and a Redis instance, the serverless concerns above mostly disappear, and Discord's Gateway connection can simply stay open. Vercel Connect, which manages platform credentials for some adapters, is optional.

The library itself costs nothing. The running costs come from elsewhere: the model provider, Redis or PostgreSQL hosting, and the platforms that charge for their APIs. WhatsApp is the obvious one, since Meta charges for business messages. These should go into the estimate from the start.

When Chat SDK Is Not the Right Choice

  • You only target one platform and the team is already comfortable with its own SDK, such as Bolt for Slack or grammY for Telegram. The extra layer adds little.
  • The bot only sends notifications, such as order updates or alerts, and never holds a conversation. A direct API call is simpler.
  • You need a platform feature the adapter does not support yet. Check the adapter page first; a partial rating usually means a workaround that may not suit you.
  • The team does not work in TypeScript. The bot can still run as a small separate service in front of a PHP or Go backend, but someone has to own and maintain it.

How We Would Approach It

  1. 1Decide the channels by who the users are. Staff are usually on Slack, Teams, or Google Chat. Customers in Indonesia are mostly on WhatsApp, with Telegram for some communities. Start with one internal and one external channel at most.
  2. 2Write the conversation for the most limited channel, then add richer cards where the platform supports them.
  3. 3Choose the state backend and the concurrency strategy per channel before the first deploy, not after users complain about missing replies.
  4. 4Keep business logic, such as looking up orders or creating tickets, in your own services. The bot handlers should call those services rather than contain the rules themselves.
  5. 5Write tests with @chat-adapter/tests, which provides Vitest factories and matchers, and add structured logging. Chat SDK already logs events such as message-dropped and message-queued, which are the first place to look when someone says the bot ignored them.
  6. 6Agree on what conversation data is stored, for how long, and how a user can ask for it to be deleted.

Key takeaways

  • Chat SDK (npm package chat) is Vercel's open-source TypeScript library for running one bot on Slack, Teams, Google Chat, Discord, Telegram, WhatsApp, and more.
  • It handles the chat platform side only; pair it with the AI SDK or TanStack AI for the model, and pass fullStream and thread.signal.
  • The same handler behaves differently per platform: WhatsApp buffers replies and allows three buttons, while modals exist only on Slack and Teams.
  • Use Redis or PostgreSQL for state in production, and change the default drop concurrency to debounce, burst, or queue for chat apps where people send several short messages.
  • Do not count on platform retries for important actions, because webhook deduplication can skip a redelivered event.
  • For customer-facing WhatsApp bots, use the official Cloud API adapter rather than unofficial Baileys-based adapters.
Share this article

Related articles

More articles on software development, AI, cloud, and infrastructure.

Hands sorting printed forms and receipts next to a calculatorAI Development

10 min read

Automating Document Data Entry With AI: Invoices, Receipts, and Forms

How AI reads invoices, receipts, ID cards, and forms and turns them into structured data, how OCR and large language models fit together, why validation and human review still matter, how to measure accuracy, and what to watch for with personal data.

A small humanoid robot sitting on a bench with a laptopAI Development

9 min read

How to Start an AI Project in Your Company

Picking a first use case that can succeed, checking whether the data is ready, choosing between an AI API and a self-hosted model, running a pilot with a test set, the cost components, and the risks to manage from the first week.

Let’s talk

Looking for a software development partner?

Tell us about your project, what you need to build, and the challenges you are facing. We can discuss the technical approach, scope, timeline, and estimated cost.

Start a conversation