WhatsApp channels let a Mastra agent receive customer messages through WhatsApp Business Cloud. Mastra handles the agent wiring and webhook route; the Chat SDK WhatsApp adapter docs cover Meta app setup, credentials, and webhook configuration.
Install the adapterDirect link to Install the adapter
Install the WhatsApp adapter from the Chat SDK:
- npm
- pnpm
- Yarn
- Bun
npm install @chat-adapter/whatsapp
pnpm add @chat-adapter/whatsapp
yarn add @chat-adapter/whatsapp
bun add @chat-adapter/whatsapp
Agent configurationDirect link to Agent configuration
Add createWhatsAppAdapter() to the agent's channels.adapters object:
import { Agent } from '@mastra/core/agent'
import { createWhatsAppAdapter } from '@chat-adapter/whatsapp'
export const whatsappAgent = new Agent({
id: 'whatsapp-agent',
name: 'WhatsApp Agent',
instructions: 'Answer customer questions and help with tasks in WhatsApp.',
model: 'openai/gpt-6.1-sol',
channels: {
adapters: {
whatsapp: createWhatsAppAdapter(),
},
},
})
Register the agent on the Mastra instance:
import { Mastra } from '@mastra/core'
import { whatsappAgent } from './agents/whatsapp-agent'
export const mastra = new Mastra({
agents: { whatsappAgent },
})
Adapter setupDirect link to Adapter setup
Follow the Chat SDK WhatsApp adapter docs for WhatsApp-specific setup, including Meta app configuration, access tokens, phone number IDs, webhook verification, and message limits.
The adapter reads WhatsApp credentials from environment variables such as:
WHATSAPP_ACCESS_TOKEN=your-meta-access-token
WHATSAPP_APP_SECRET=your-meta-app-secret
WHATSAPP_PHONE_NUMBER_ID=your-whatsapp-phone-number-id
WHATSAPP_VERIFY_TOKEN=your-webhook-verify-token
Webhook URLDirect link to Webhook URL
Mastra generates the WhatsApp webhook route from the agent ID and adapter key:
/api/agents/whatsapp-agent/channels/whatsapp/webhook
Use your public Mastra server URL as the base URL:
https://your-app.example.com/api/agents/whatsapp-agent/channels/whatsapp/webhook
Use this URL for incoming WhatsApp event delivery. The generated Mastra route handles POST events from WhatsApp. Follow the Chat SDK WhatsApp adapter docs for the Meta callback and webhook verification flow.