> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp

> Deploy agents, teams, or workflows as WhatsApp bots via the WhatsApp Interface using Agno.

The WhatsApp interface lets you deploy agents, teams, or workflows as WhatsApp bots that handle text, images, video, audio, and documents.

## Setup

Follow the [WhatsApp setup guide](https://agno-v2.mintlify.site/agent-os/interfaces/whatsapp/setup.md) to create a Meta App, configure the WhatsApp Business API, and set up webhooks.

Install dependencies: `uv pip install 'agno[os]' openai anthropic ddgs`

Required configuration:

* `WHATSAPP_ACCESS_TOKEN` (from [Meta App Dashboard](https://developers.facebook.com/apps/) > WhatsApp > API Setup)
* `WHATSAPP_PHONE_NUMBER_ID` (from WhatsApp > API Setup)
* `WHATSAPP_VERIFY_TOKEN` (any string you choose for webhook verification)
* `WHATSAPP_APP_SECRET` (from App Settings > Basic, used to validate incoming webhook signatures)
* Webhook URL set to `{prefix}/webhook` (use [ngrok](https://ngrok.com) for local development)

## Example Usage

**Agent**

```python basic.py theme={null}
from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIChat
from agno.os.app import AgentOS
from agno.os.interfaces.whatsapp import Whatsapp

agent_db = SqliteDb(db_file="tmp/persistent_memory.db")

basic_agent = Agent(
    name="Basic Agent",
    model=OpenAIChat(id="gpt-5.4-mini"),
    db=agent_db,
    add_history_to_context=True,
    num_history_runs=3,
    add_datetime_to_context=True,
    markdown=True,
)

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

if __name__ == "__main__":
    agent_os.serve(app="basic:app", reload=True)
```

**Team**

```python support_team.py theme={null}
from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.anthropic import Claude
from agno.os.app import AgentOS
from agno.os.interfaces.whatsapp import Whatsapp
from agno.team import Team
from agno.tools.websearch import WebSearchTools

model = Claude(id="claude-sonnet-4-6")
team_db = SqliteDb(db_file="tmp/support_team.db")

researcher = Agent(
    name="Researcher",
    role="Find accurate, up-to-date information on the web",
    model=model,
    tools=[WebSearchTools()],
)

writer = Agent(
    name="Writer",
    role="Turn research into clear, friendly WhatsApp replies",
    model=model,
)

support_team = Team(
    name="Support Team",
    model=model,
    members=[researcher, writer],
    db=team_db,
    add_history_to_context=True,
    num_history_runs=3,
    markdown=True,
)

agent_os = AgentOS(
    teams=[support_team],
    interfaces=[Whatsapp(team=support_team)],
)
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="support_team:app", reload=True)
```

**Workflow**

```python multimodal_workflow.py theme={null}
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.os.app import AgentOS
from agno.os.interfaces.whatsapp import Whatsapp
from agno.tools.websearch import WebSearchTools
from agno.workflow import Parallel, Step, Workflow

analyst = Agent(
    name="Visual Analyst",
    model=OpenAIChat(id="gpt-5.4-mini"),
)

researcher = Agent(
    name="Web Researcher",
    model=OpenAIChat(id="gpt-5.4-mini"),
    tools=[WebSearchTools()],
)

creative_workflow = Workflow(
    name="Creative Pipeline",
    steps=[
        Parallel(
            Step(agent=analyst, name="Analyze"),
            Step(agent=researcher, name="Research"),
        ),
    ],
)

agent_os = AgentOS(
    workflows=[creative_workflow],
    interfaces=[Whatsapp(workflow=creative_workflow)],
)
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="multimodal_workflow:app", reload=True)
```

> [!NOTE]
>
> See [more examples](https://agno-v2.mintlify.site/agent-os/usage/interfaces/whatsapp/basic.md) including [media agents](https://agno-v2.mintlify.site/agent-os/usage/interfaces/whatsapp/agent-with-media.md), [image generation](https://agno-v2.mintlify.site/agent-os/usage/interfaces/whatsapp/image-generation-tools.md), [reasoning](https://agno-v2.mintlify.site/agent-os/usage/interfaces/whatsapp/reasoning-agent.md), and [multiple bots](https://agno-v2.mintlify.site/examples/agent-os/whatsapp/multiple-instances.md).

## Sessions

Each WhatsApp user gets a single session scoped to their phone number.

> [!NOTE]
>
> Session format: `wa:{entity_id}:{user_id}`. For example, an agent named "Basic Agent" talking to user +1234567890 produces `wa:basic-agent:1234567890` (AgentOS generates the ID from the name).

Users can send `/new` to start a fresh session. The old session is preserved in the database, and a new session ID is created with a random suffix. This requires a `db` on the agent, team, or workflow.

## Media

Users can send images, video, audio, and documents to the bot. Media is downloaded from Meta's servers and passed to the agent automatically. Agents can send media back in their responses.

See the [media agent example](https://agno-v2.mintlify.site/agent-os/usage/interfaces/whatsapp/agent-with-media.md) for a complete multimodal agent, and the [reference page](https://agno-v2.mintlify.site/agent-os/interfaces/whatsapp/reference.md) for supported message types.

## WhatsAppTools

`WhatsAppTools` lets your agents send interactive messages: reply buttons, list menus, images, documents, locations, and reactions.

```python theme={null}
from agno.tools.whatsapp import WhatsAppTools

agent = Agent(
    tools=[WhatsAppTools(
        enable_send_reply_buttons=True,
        enable_send_list_message=True,
        enable_send_location=True,
    )],
)
```

See the [interactive concierge example](https://github.com/agno-agi/agno/blob/main/cookbook/05_agent_os/19_whatsapp/interactive.py) for a full agent using all interactive features.

For parameters and methods, see the [WhatsAppTools reference](https://agno-v2.mintlify.site/tools/toolkits/social/whatsapp.md).

## Multi-Instance

Run multiple bots on the same server with different `prefix` values:

```python theme={null}
agent_os = AgentOS(
    agents=[basic_agent, research_agent],
    interfaces=[
        Whatsapp(
            agent=basic_agent,
            prefix="/basic",
            access_token=getenv("BASIC_WHATSAPP_ACCESS_TOKEN"),
            phone_number_id=getenv("BASIC_WHATSAPP_PHONE_NUMBER_ID"),
            verify_token=getenv("BASIC_WHATSAPP_VERIFY_TOKEN"),
        ),
        Whatsapp(
            agent=research_agent,
            prefix="/web-research",
            access_token=getenv("RESEARCH_WHATSAPP_ACCESS_TOKEN"),
            phone_number_id=getenv("RESEARCH_WHATSAPP_PHONE_NUMBER_ID"),
            verify_token=getenv("RESEARCH_WHATSAPP_VERIFY_TOKEN"),
        ),
    ],
)
```

Each instance gets its own route prefix, session namespace, and Meta App credentials.

> [!TIP]
>
> Each Meta App can only have one webhook callback URL, so multi-instance setups require separate Meta Apps (one per bot), each with its own phone number.

## Phone Number Encryption

> [!NOTE]
>
> Enable with `enable_encryption=True` to encrypt phone numbers before storing them as `user_id`. Raw numbers are never written to the database.

```python theme={null}
Whatsapp(agent=my_agent, enable_encryption=True)
# Set WHATSAPP_ENCRYPTION_KEY env var (64 hex chars = 32 bytes)
```

Phone numbers are encrypted with AES-256-GCM using a deterministic nonce, so the same phone always maps to the same `user_id`. Requires the `cryptography` package.

## Security

Every incoming webhook is verified using HMAC-SHA256 signature validation:

1. The `X-Hub-Signature-256` header is extracted
2. A signature is computed: `HMAC-SHA256(app_secret, request_body)`
3. The computed signature is compared using constant-time comparison (`hmac.compare_digest`)

> [!WARNING]
>
> If `WHATSAPP_APP_SECRET` is not set, the server returns a 500 error unless `WHATSAPP_SKIP_SIGNATURE_VALIDATION=true` is set. Always configure the App Secret for production. Find it at **App Settings > Basic** in your [Meta App Dashboard](https://developers.facebook.com/apps/).

## Troubleshooting

> **No messages received**
>
> **Cause:** Webhook not configured or not subscribed to the `messages` field.
>
> **Fix:** In your [Meta App Dashboard](https://developers.facebook.com/apps/), go to **WhatsApp > Configuration** and verify the callback URL matches your tunnel URL (e.g., `https://your-tunnel.ngrok.io/whatsapp/webhook`). Click "Manage" and confirm you're subscribed to the `messages` field.

> **403 on webhook**
>
> **Cause:** Invalid App Secret or missing signature validation config.
>
> **Fix:** Verify `WHATSAPP_APP_SECRET` matches the value under **App Settings > Basic** in your [Meta App Dashboard](https://developers.facebook.com/apps/). Use `WHATSAPP_SKIP_SIGNATURE_VALIDATION=true` only for isolated localhost payload tests that are not network-reachable.

> **Webhook verification fails**
>
> **Cause:** Verify token mismatch or server not running.
>
> **Fix:** Ensure `WHATSAPP_VERIFY_TOKEN` matches the value you entered in the Meta webhook configuration. Your server must be running when you click "Verify and save".

> **Media not sending**
>
> **Cause:** Expired or insufficient access token.
>
> **Fix:** Temporary tokens expire after \~24 hours. For production, create a permanent [System User token](https://developers.facebook.com/docs/whatsapp/business-management-api/get-started#system-user-access-tokens) via Meta Business Manager. Ensure the token has `whatsapp_business_messaging` permission.

> **Bot not replying**
>
> **Cause:** Missing environment variables or agent errors.
>
> **Fix:** Check application logs. Common causes: `WHATSAPP_ACCESS_TOKEN` not set, expired token, or an error in your agent's tools or model configuration.

> **SSL certificate errors**
>
> **Cause:** macOS system Python missing root certificates.
>
> **Fix:** Set the `SSL_CERT_FILE` environment variable:
>
> ```bash theme={null}
> export SSL_CERT_FILE=$(python3 -c "import certifi; print(certifi.where())")
> ```

## Developer Resources

> **[Interface Reference](https://agno-v2.mintlify.site/agent-os/interfaces/whatsapp/reference.md)**
>
> All parameters, endpoints, and session handling details.

> **[Setup Guide](https://agno-v2.mintlify.site/agent-os/interfaces/whatsapp/setup.md)**
>
> Create a Meta App, configure webhooks, and deploy step by step.

> **[WhatsAppTools Reference](https://agno-v2.mintlify.site/tools/toolkits/social/whatsapp.md)**
>
> Toolkit parameters and methods for interactive messages, media, and locations.

> **[Usage Examples](https://agno-v2.mintlify.site/agent-os/usage/interfaces/whatsapp/basic.md)**
>
> Agents, teams, media, image generation, reasoning, and more.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.