Should I use the Chat SDK adapter or @kapso/whatsapp-cloud-api directly?

Use @kapso/chat-adapter for Chat SDK agents and threaded replies. Use @kapso/whatsapp-cloud-api directly for lower-level WhatsApp API calls such as raw templates, flows, and catalogs.

What state should I use in production?

@chat-adapter/state-memory is useful for local development. Production agents should use durable Chat SDK state.

WhatsApp Chat SDK for AI agents

Q: What does @kapso/chat-adapter do?

@kapso/chat-adapter lets a Chat SDK agent receive Kapso WhatsApp webhooks, reply in threads, send buttons or media, and read Kapso conversation history.

Use @kapso/chat-adapter when a Chat SDK agent needs to receive Kapso WhatsApp webhooks, reply in threads, send buttons or media, and read conversation history.

Start building Read Chat SDK docs

Give Chat SDK agents a WhatsApp channel

The adapter keeps the WhatsApp transport close to Chat SDK primitives: threads, direct messages, cards, files, and history.

Receive Kapso webhooks

Forward your public POST route to bot.webhooks.kapso(request) for inbound WhatsApp events.

Reply in threads

Handle direct messages and post replies through Chat SDK thread APIs.

Open outbound DMs

Use the Kapso adapter openDM method with KAPSO_PHONE_NUMBER_ID for outbound WhatsApp conversations.

Send buttons and media

Send Chat SDK cards with WhatsApp reply buttons and pass files as Chat SDK attachments.

Read history

Fetch Kapso-backed message history and enrich threads with contact and conversation records.

Drop lower when needed

Use @kapso/whatsapp-cloud-api directly for raw templates, flows, catalogs, or lower-level WhatsApp API calls.

Install the adapter and set Kapso env vars

Start with memory state locally, then move to durable Chat SDK state before production traffic.

Chat SDK setup

npm install chat @kapso/chat-adapter @chat-adapter/state-memory

KAPSO_API_KEY=your_project_api_key
KAPSO_PHONE_NUMBER_ID=your_phone_number_id
KAPSO_WEBHOOK_SECRET=your_webhook_secret

Requires Node.js >= 20.19.

KAPSO_API_KEY is required for sends, history, contacts, conversations, and media.

KAPSO_PHONE_NUMBER_ID is recommended and required for openDM().

KAPSO_WEBHOOK_SECRET is recommended for signature verification.

Production constraints worth knowing

WhatsApp is a real messaging channel, so the agent adapter should keep delivery, media, and webhook rules explicit.

Verify signatures

Use the same webhook secret in Kapso and in the adapter so inbound events can be verified.

Use durable state

Do not use memory state for production conversations that need continuity across restarts.

Respect button limits

WhatsApp reply buttons support up to 3 buttons, with labels from 1 to 20 characters.

Build the agent around real WhatsApp history

Connect the adapter, receive one inbound message, reply through a thread, and let Kapso keep the conversation record visible.

Start free Read Chat SDK docs