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.
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. |
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 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. 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 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 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) | Uploaded; delivery still depends on provider MIME/codec and size requirements. |
| Audio (WAV or raw PCM) | The adapter accepts WAV and converts PCM to WAV before upload, but WAV is outside the documented WhatsApp audio format list. Supply an accepted encoded format, such as MP3, instead. |
| Documents | Uploaded with detected MIME type and filename. |
| Long text (>4096 chars) | Split into numbered batches: [1/3], [2/3], [3/3]. |
See the current WhatsApp media format list for provider constraints. The adapter does not transcode WAV into MP3.