> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Reference

> Interface parameters, endpoints, and webhook handling for the WhatsApp interface.

## Interface Parameters

Pass one of `agent`, `team`, or `workflow` to the `Whatsapp` constructor.

```python theme={null}
from agno.os.interfaces.whatsapp import Whatsapp

Whatsapp(agent=my_agent, prefix="/whatsapp")
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `agent` | `Optional[Union[Agent, RemoteAgent]]` | `None` | Agno `Agent` instance. |
| `team` | `Optional[Union[Team, RemoteTeam]]` | `None` | Agno `Team` instance. |
| `workflow` | `Optional[Union[Workflow, RemoteWorkflow]]` | `None` | Agno `Workflow` instance. |
| `prefix` | `str` | `"/whatsapp"` | URL prefix for WhatsApp endpoints (e.g., `/whatsapp` means webhooks arrive at `/whatsapp/webhook`). |
| `tags` | `Optional[List[str]]` | `None` | FastAPI route tags for API documentation. Defaults to `["Whatsapp"]`. |
| `show_reasoning` | `bool` | `False` | When `True`, sends the model's reasoning content as an italicized message before the main response. |
| `send_user_number_to_context` | `bool` | `False` | When `True`, injects the user's phone number and incoming message ID into the agent's context via `dependencies`. |
| `access_token` | `Optional[str]` | `None` | WhatsApp Business API access token. Falls back to `WHATSAPP_ACCESS_TOKEN` environment variable. |
| `phone_number_id` | `Optional[str]` | `None` | WhatsApp Business phone number ID. Falls back to `WHATSAPP_PHONE_NUMBER_ID` environment variable. |
| `verify_token` | `Optional[str]` | `None` | Webhook verification token. Falls back to `WHATSAPP_VERIFY_TOKEN` environment variable. |
| `media_timeout` | `int` | `30` | Timeout in seconds for media downloads from and uploads to [Meta's media API](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media). |
| `enable_encryption` | `bool` | `False` | When `True`, encrypts user phone numbers with AES-256-GCM before storing them as `user_id`. Requires `WHATSAPP_ENCRYPTION_KEY` or the `encryption_key` parameter. |
| `encryption_key` | `Optional[str]` | `None` | 32-byte hex key (64 characters) for phone number encryption. Falls back to `WHATSAPP_ENCRYPTION_KEY` environment variable. |

## Endpoints

Available at the `/whatsapp` prefix (customizable with `prefix`).

### `GET {prefix}/status`

Returns `{"status": "available"}`. Use for health checks.

### `GET {prefix}/webhook`

Handles [WhatsApp webhook verification](https://developers.facebook.com/docs/graph-api/webhooks/getting-started#verification-requests) during setup.

| Status | Description |
| - | - |
| **200** | Verification successful. Returns the `hub.challenge` value. |
| **400** | Missing `hub.challenge` parameter. |
| **403** | `hub.verify_token` does not match `WHATSAPP_VERIFY_TOKEN`, or `hub.mode` is not `subscribe`. |
| **500** | `WHATSAPP_VERIFY_TOKEN` is not set. |

### `POST {prefix}/webhook`

Receives all [WhatsApp webhook events](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components). Processing happens in the background so Meta gets a response within their timeout window.

| Status | Description |
| - | - |
| **200** `{"status": "processing"}` | Messages received and queued for background processing. |
| **200** `{"status": "ignored"}` | Non-WhatsApp event (e.g., `object` is not `whatsapp_business_account`). |
| **403** | Invalid `X-Hub-Signature-256` signature. |
| **500** | `WHATSAPP_APP_SECRET` not set and `WHATSAPP_SKIP_SIGNATURE_VALIDATION` not enabled. |

### Built-in Message Handling

| Message Type | Behavior |
| - | - |
| Text | Passed directly to the agent as the input message. |
| Image, video, audio, document | Downloaded from [Meta's media API](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media) and passed as Agno media objects (`Image`, `Video`, `Audio`, `File`). |
| Interactive (button reply) | The selected button's `title` is extracted and passed as text input. |
| Interactive (list reply) | The selected row's `title` and `description` are extracted and passed as text input. |
| `/new` command | Creates a new session. Old session is preserved. Requires a `db` on the agent/team/workflow. |
| Unsupported types | Stickers, contacts, and other types receive a "not supported yet" reply. |

### Outgoing Media

Agent responses containing media are automatically uploaded to [Meta's media API](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media) and sent to the user.

| Format | Behavior |
| - | - |
| Images (JPEG, PNG) | Uploaded and sent. Other formats (GIF, WebP, HEIC) are skipped. |
| Video | Uploaded and sent with the media object's MIME type, defaulting to `video/mp4`. |
| Audio (AAC, MP4, MPEG, AMR, OGG, WAV) | Uploaded and sent directly. |
| Audio (raw PCM, e.g., from TTS) | Auto-converted to WAV before upload. |
| Documents | Uploaded with detected MIME type and filename. |
| Long text (>4096 chars) | Split into numbered batches: `[1/3]`, `[2/3]`, `[3/3]`. |

## Developer Resources

> **[WhatsApp Guide](https://agno-v2.mintlify.site/agent-os/interfaces/whatsapp/introduction.md)**
>
> Setup, code examples, media handling, and troubleshooting.

> **[WhatsAppTools Reference](https://agno-v2.mintlify.site/tools/toolkits/social/whatsapp.md)**
>
> Toolkit parameters and methods for interactive messages, media, and locations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.