Skip to main content
Use the WhatsApp interface to serve Agents or Teams via WhatsApp. It mounts webhook routes on a FastAPI app and sends responses back to WhatsApp users and threads.

​
Setup

Follow the WhatsApp setup guide in the Whatsapp Cookbook. You will need environment variables:
  • WHATSAPP_ACCESS_TOKEN
  • WHATSAPP_PHONE_NUMBER_ID
  • WHATSAPP_VERIFY_TOKEN
  • Optional (production): WHATSAPP_APP_SECRET and APP_ENV=production
The user’s phone number is automatically used as the user_id for runs. This ensures that sessions and memory are appropriately scoped to the user.The phone number is also used for the session_id so a single Whatsapp conversation will be a single session. It is important to take this into account when considering session history.

​
Example Usage

Create an agent, expose it with the Whatsapp interface, and serve via AgentOS: 
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.os import AgentOS
from agno.os.interfaces.whatsapp import Whatsapp

image_agent = Agent(
    model=OpenAIChat(id="gpt-5-mini"), # Ensure OPENAI_API_KEY is set
    tools=[OpenAITools(image_model="gpt-image-1")],
    markdown=True,
    add_history_to_context=True,
)

agent_os = AgentOS(
    agents=[image_agent],
    interfaces=[Whatsapp(agent=image_agent)],
)
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="basic:app", port=8000, reload=True)
See more in our cookbook examples.

​
Core Components

  • Whatsapp (interface): Wraps an Agno Agent or Team for WhatsApp via FastAPI.
  • AgentOS.serve: Serves the FastAPI app using Uvicorn.

​
Whatsapp Interface

Main entry point for Agno WhatsApp applications.

​
Initialization Parameters

ParameterTypeDefaultDescription
agentOptional[Agent]NoneAgno Agent instance.
teamOptional[Team]NoneAgno Team instance.
Provide agent or team.

​
Key Method

MethodParametersReturn TypeDescription
get_routeruse_async: bool = TrueAPIRouterReturns the FastAPI router and attaches endpoints.

​
Endpoints

Mounted under the /whatsapp prefix:

​
GET /whatsapp/status

  • Health/status of the interface.

​
GET /whatsapp/webhook

  • Verifies WhatsApp webhook (hub.challenge).
  • Returns hub.challenge on success; 403 on token mismatch; 500 if WHATSAPP_VERIFY_TOKEN missing.

​
POST /whatsapp/webhook

  • Receives WhatsApp messages and events.
  • Validates signature (X-Hub-Signature-256); bypassed in development mode.
  • Processes text, image, video, audio, and document messages via the agent/team.
  • Sends replies (splits long messages; uploads and sends generated images).
  • Responses: 200 {"status": "processing"} or {"status": "ignored"}, 403 invalid signature, 500 errors.
⌘I