Serve an Agent on WhatsApp

Mount one Agent on AgentOS's WhatsApp interface. The interface verifies Meta webhooks, maps each phone number to a persistent session, and sends the Agent's response back through the WhatsApp Cloud API.

basic.py

"""
Serve an Agent on WhatsApp
==========================

Mount one Agent on AgentOS's WhatsApp interface. The interface verifies Meta
webhooks, maps each phone number to a persistent session, and sends the Agent's
response back through the WhatsApp Cloud API.

Prerequisites: OPENAI_API_KEY and the four WHATSAPP_* credentials in README.md
Run: .venvs/demo/bin/python cookbook/05_agent_os/19_whatsapp/basic.py
Try: GET http://localhost:7777/whatsapp/status, then message the configured number
"""

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
from agno.os.interfaces.whatsapp import Whatsapp

# ---------------------------------------------------------------------------
# Create the WhatsApp AgentOS
# ---------------------------------------------------------------------------

db = SqliteDb(
    id="whatsapp-basic-db",
    db_file="tmp/whatsapp_basic.db",
)

assistant = Agent(
    id="whatsapp-assistant",
    name="WhatsApp Assistant",
    model=OpenAIResponses(id="gpt-5.5"),
    db=db,
    add_history_to_context=True,
    num_history_runs=3,
    instructions=[
        "You are chatting with the user on WhatsApp.",
        "Keep responses conversational, concise, and easy to read on a phone.",
    ],
)

agent_os = AgentOS(
    id="whatsapp-basic-os",
    description="A minimal AgentOS exposed through the WhatsApp interface.",
    agents=[assistant],
    interfaces=[Whatsapp(agent=assistant)],
)
app = agent_os.get_app()

# ---------------------------------------------------------------------------
# Run the WhatsApp Server
# ---------------------------------------------------------------------------

if __name__ == "__main__":
    agent_os.serve(app=app)

Run the Example

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate

Install dependencies

uv pip install -U "agno[os]" openai

Export environment variables

export OPENAI_API_KEY="your_openai_api_key_here"
export WHATSAPP_ACCESS_TOKEN="your_whatsapp_access_token_here"
export WHATSAPP_APP_SECRET="your_whatsapp_app_secret_here"
export WHATSAPP_PHONE_NUMBER_ID="your_whatsapp_phone_number_id_here"
export WHATSAPP_VERIFY_TOKEN="your_whatsapp_verify_token_here"

Expose the server

Install ngrok and start ngrok http 7777 in another terminal. Copy its public HTTPS URL and keep the tunnel running.

Run the example

Save the code above as basic.py, then run:

python basic.py

Configure Meta webhooks

Keep Python and ngrok running. Follow WhatsApp setup. Configure the appropriate callback using your public HTTPS origin and the matching verification token:

Interface	Callback path	Verification token
WhatsApp	`/whatsapp/webhook`	`WHATSAPP_VERIFY_TOKEN`

Complete the GET verification challenge and subscribe to the messages field. Add and verify a test recipient when using Meta's test phone number, then message that number. Update callback URLs when the tunnel changes.

Full source: cookbook/05_agent_os/19_whatsapp/basic.py