> ## Documentation Index > Fetch the complete documentation index at: https://docs.agno.com/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`. | | **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 as `video/mp4`. | | Audio (AAC, MP4, MPEG, 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 Setup, code examples, media handling, and troubleshooting. Toolkit parameters and methods for interactive messages, media, and locations.