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

WhatsApp Guide

Setup, code examples, media handling, and troubleshooting.

WhatsAppTools Reference

Toolkit parameters and methods for interactive messages, media, and locations.