Skip to main content

WhatsApp

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 adapter
Direct link to Install the adapter

Install the WhatsApp adapter from the Chat SDK:

npm install @chat-adapter/whatsapp

Agent configuration
Direct link to Agent configuration

Add createWhatsAppAdapter() to the agent's channels.adapters object:

src/mastra/agents/whatsapp-agent.ts
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-5.5',
  channels: {
    adapters: {
      whatsapp: createWhatsAppAdapter(),
    },
  },
})

Register the agent on the Mastra instance:

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { whatsappAgent } from './agents/whatsapp-agent'

export const mastra = new Mastra({
  agents: { whatsappAgent },
})

Adapter setup
Direct 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:

.env
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 URL
Direct 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.

On this page