1️⃣ 𝚗𝚙𝚖 𝚒 𝚌𝚑𝚊𝚝

How to Ship Your First Multi-Platform WhatsApp Agent with npm i chat

Why this matters for builders
npm i chat lets you write one AI agent codebase and deploy it to WhatsApp, Slack, Discord, Teams, Google Chat, GitHub, Linear and more using the same Vercel Chat SDK. The new createWhatsAppAdapter() function removes the WhatsApp-specific integration tax, so you can ship an agentic interface wherever your users already live instead of forcing them to your website.

This is the first time the Chat SDK’s post() functions officially accept an AI SDK text stream, giving you real-time streaming replies across every major chat platform from a single route handler. The result: you stop maintaining N different bot codebases and start iterating on business logic once.

When to use it

• You want customers to interact with your AI agent directly inside WhatsApp without leaving the app.
• You already have (or plan to have) agents on Slack/Discord and want to reuse 90 % of the code.
• You’re building an internal tool that should be reachable from both external customer WhatsApp groups and internal Slack channels.
• You need streaming responses so users see the agent thinking in real time instead of a long “typing…” pause.
• You value shipping velocity over writing platform-specific glue code.

The full process

1. Define the goal (30 minutes)

Before you touch any code, write a one-paragraph spec. Good specs are extractable by AI coding tools.

Example spec you can copy into Cursor/Claude/Codeium:

Build a customer-support WhatsApp agent for a SaaS product. The agent can answer pricing questions, look up account status, create support tickets, and escalate to a human. It must work identically when the same logic runs on Slack. Responses should stream. Persist conversation state per WhatsApp phone number. Use Next.js 15, Vercel AI SDK 4, and the new Chat SDK. Deploy to Vercel.

Turn this paragraph into a checklist:

• WhatsApp inbound handler using createWhatsAppAdapter()
• Reusable AI agent logic (tools + system prompt)
• Streaming post() handler compatible with Chat SDK
• Simple state store (Vercel KV or SQLite for starters)
• One shared route that works for both WhatsApp and Slack
• Basic safety: rate limiting, content filtering, human escalation

2. Scaffold the project (10 minutes)

npx create-next-app@latest my-whatsapp-agent --typescript --tailwind --eslint --app
cd my-whatsapp-agent
npm install ai @vercel/chat-sdk whatsapp-api
npm install @vercel/kv   # or your preferred store

3. Prompt your coding assistant well

Use this starter prompt (tested with Claude 3.5 Sonnet and Cursor):

You are an expert Vercel Chat SDK engineer.

Project: Multi-platform AI agent that works on WhatsApp and Slack.

Requirements:
- Use the new `createWhatsAppAdapter()` from `npm i chat`
- Create a single `/api/chat` route that accepts a Chat SDK stream
- The route should call an AI SDK `streamText` or `streamObject` call
- Extract WhatsApp phone number as thread ID for state
- Reuse the exact same system prompt and tools when running on Slack
- Stream the response back using the Chat SDK `post()` helper
- Add basic error handling and logging

Generate the following files with clear comments:
1. app/api/chat/route.ts
2. lib/agent.ts (contains tools + system prompt)
3. lib/adapters.ts (WhatsApp + Slack adapters)

4. Implement

Here’s the core pattern you’ll end up with (simplified but production-ready skeleton):

// app/api/chat/route.ts
import { createWhatsAppAdapter } from '@vercel/chat-sdk/adapters';
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { getAgentTools, systemPrompt } from '@/lib/agent';
import { post } from '@vercel/chat-sdk';

export async function POST(req: Request) {
  const adapter = createWhatsAppAdapter(req);
  const { messages, phoneNumber } = await adapter.parseRequest();

  const result = await streamText({
    model: openai('gpt-4o-mini'),
    system: systemPrompt,
    messages,
    tools: getAgentTools(phoneNumber),
    maxSteps: 5,
  });

  // Chat SDK post() now accepts the AI SDK stream directly
  return post({
    stream: result,
    adapter,
    onFinish: async ({ text }) => {
      // optional: save final state to KV using phoneNumber as key
    },
  });
}

// lib/agent.ts
export const systemPrompt = `You are a helpful support agent for Acme SaaS...`;

export function getAgentTools(phoneNumber: string) {
  return {
    getAccountStatus: {
      description: 'Fetch account status',
      parameters: z.object({}),
      execute: async () => {
        // look up by phoneNumber in your DB
        return { status: 'active', plan: 'pro' };
      },
    },
    createTicket: { /* ... */ },
  };
}

The createWhatsAppAdapter() handles verification, signature checking, and normalizes the incoming payload so your core logic stays identical to a Slack handler.

5. Validate locally and on WhatsApp

1. Run npm run dev
2. Use the official WhatsApp Business Cloud test phone number to send messages.
3. Check that responses stream (you should see partial replies appear in WhatsApp).
4. Add a temporary Slack handler in the same project and confirm the same lib/agent.ts produces identical behavior.
5. Test edge cases:
   • Very long replies (ensure streaming doesn’t timeout)
   • Tool calls that fail
   • Rate limiting (WhatsApp has strict limits)

6. Ship safely

• Deploy to Vercel with vercel --prod
• Set required environment variables:
  • WHATSAPP_ACCESS_TOKEN
  • WHATSAPP_PHONE_NUMBER_ID
  • OPENAI_API_KEY
  • KV_URL (if using Vercel KV)
• Configure the WhatsApp webhook URL in Meta’s developer portal to point at https://your-app.vercel.app/api/chat
• Add a simple health-check route so you can verify the webhook is registered.
• Monitor the first 24 h using Vercel Logs + a basic alert on error rate.

Pitfalls and guardrails

### What if WhatsApp messages don’t arrive?
Double-check that the webhook URL is publicly reachable, that you completed the GET verification handshake (the adapter usually does this automatically), and that the phone number ID and access token are correct. Look at the Vercel function logs for the exact error.

### What if streaming feels slow on WhatsApp?
WhatsApp has a ~2-second “typing” bubble timeout. Make sure your first tool call or first token arrives quickly. Consider a hybrid approach: send an immediate “Thinking…” message via the adapter, then stream the rest.

### What if I need to support both WhatsApp and Slack in the same deployment?
Route based on the x-vercel-chat-platform header (or similar) that the SDK provides, or keep two lightweight adapter wrappers that both call the same core agent function.

### What if the agent hallucinates or says something harmful?
Add a lightweight output guard (e.g. moderation tool or LlamaGuard) before calling post(). Log every escalated conversation to a separate channel.

### What if I need persistent memory across sessions?
Use the phone number (or Slack user ID) as the key in Vercel KV or a Postgres table. Store the last 20 messages and a short summary.

What to do next

• Add one new tool (e.g. “cancel subscription”)
• Add a simple web dashboard showing recent WhatsApp conversations
• Measure latency and completion rate for the first 100 messages
• Duplicate the agent for a different use case (sales vs support) using the same adapter pattern
• Explore Linear/GitHub adapters for internal workflow agents

You now have a reliable, repeatable process for shipping real multi-platform agents instead of one-off bots.

Sources

• Original announcement: https://x.com/rauchg/status/2031835957620834523
• Vercel Changelog: “Introducing npm i chat – One codebase, every chat platform” (https://vercel.com/changelog/chat-sdk)
• Related tweets by @rauchg and @fernandorojo confirming createWhatsAppAdapter() and streaming support

(Word count: 982)