@mastra/core/dist/docs/references/docs-capabilities-channels-whatsapp.md

> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# 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

Install the WhatsApp adapter from the Chat SDK:

**npm**:

```bash
npm install @chat-adapter/whatsapp
```

**pnpm**:

```bash
pnpm add @chat-adapter/whatsapp
```

**Yarn**:

```bash
yarn add @chat-adapter/whatsapp
```

**Bun**:

```bash
bun add @chat-adapter/whatsapp
```

## Agent configuration

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

```typescript
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.6-sol',
  channels: {
    adapters: {
      whatsapp: createWhatsAppAdapter(),
    },
  },
})
```

Register the agent on the Mastra instance:

```typescript
import { Mastra } from '@mastra/core'
import { whatsappAgent } from './agents/whatsapp-agent'

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

## Adapter setup

Follow the [Chat SDK WhatsApp adapter docs](https://chat-sdk.dev/adapters/official/whatsapp) 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:

```bash
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

Mastra generates the WhatsApp webhook route from the agent ID and adapter key:

```text
/api/agents/whatsapp-agent/channels/whatsapp/webhook
```

Use your public Mastra server URL as the base URL:

```text
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.

## Related

- [Channels overview](https://mastra.ai/docs/capabilities/channels/overview)
- [More](https://mastra.ai/docs/capabilities/channels/other-adapters)