Mount Multiple WhatsApp Bot Instances

Mount two independently configured WhatsApp interfaces on one AgentOS. Each interface has its own prefix, access token, phone-number ID, and verification token, so its Meta webhook points at a distinct callback URL.

multiple_instances.py

"""
Mount Multiple WhatsApp Bot Instances
=====================================

Mount two independently configured WhatsApp interfaces on one AgentOS. Each
interface has its own prefix, access token, phone-number ID, and verification
token, so its Meta webhook points at a distinct callback URL.

Prerequisites: OPENAI_API_KEY and the six bot-specific variables in README.md
Run: .venvs/demo/bin/python cookbook/05_agent_os/19_whatsapp/multiple_instances.py
Try: GET /basic/status and /web-research/status, then verify both webhook URLs

Security note: signed POST requests currently share one global
WHATSAPP_APP_SECRET. See README.md before deploying separate Meta apps.
"""

from os import getenv

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
from agno.tools.websearch import WebSearchTools

def required_env(name: str) -> str:
    value = getenv(name)
    if not value:
        raise ValueError(f"{name} is required for this example")
    return value

# ---------------------------------------------------------------------------
# Create the Multi-Bot WhatsApp AgentOS
# ---------------------------------------------------------------------------

db = SqliteDb(
    id="whatsapp-multiple-db",
    db_file="tmp/whatsapp_multiple.db",
)

basic_bot = Agent(
    id="whatsapp-basic-bot",
    name="WhatsApp Basic Bot",
    model=OpenAIResponses(id="gpt-5.5"),
    db=db,
    add_history_to_context=True,
    num_history_runs=3,
    instructions="Answer clearly and concisely.",
)

research_bot = Agent(
    id="whatsapp-research-bot",
    name="WhatsApp Research Bot",
    model=OpenAIResponses(id="gpt-5.5"),
    db=db,
    tools=[WebSearchTools()],
    add_history_to_context=True,
    num_history_runs=3,
    instructions="Research current information and cite useful sources.",
)

agent_os = AgentOS(
    id="whatsapp-multiple-os",
    description="Two WhatsApp bots mounted at separate AgentOS prefixes.",
    agents=[basic_bot, research_bot],
    interfaces=[
        Whatsapp(
            agent=basic_bot,
            prefix="/basic",
            access_token=required_env("BASIC_WHATSAPP_ACCESS_TOKEN"),
            phone_number_id=required_env("BASIC_WHATSAPP_PHONE_NUMBER_ID"),
            verify_token=required_env("BASIC_WHATSAPP_VERIFY_TOKEN"),
        ),
        Whatsapp(
            agent=research_bot,
            prefix="/web-research",
            access_token=required_env("RESEARCH_WHATSAPP_ACCESS_TOKEN"),
            phone_number_id=required_env("RESEARCH_WHATSAPP_PHONE_NUMBER_ID"),
            verify_token=required_env("RESEARCH_WHATSAPP_VERIFY_TOKEN"),
        ),
    ],
)
app = agent_os.get_app()

# ---------------------------------------------------------------------------
# Run the Multi-Bot WhatsApp Server
# ---------------------------------------------------------------------------

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

Both interfaces validate incoming signatures with the process-wide WHATSAPP_APP_SECRET. Use phone numbers belonging to the same Meta app for this setup; different signing secrets require separate processes. Per-instance tokens and callback prefixes do not provide per-instance app-secret validation.

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]" ddgs openai

Export environment variables

export OPENAI_API_KEY="your_openai_api_key_here"
export WHATSAPP_APP_SECRET="your_whatsapp_app_secret_here"
export BASIC_WHATSAPP_ACCESS_TOKEN="your_basic_whatsapp_access_token_here"
export BASIC_WHATSAPP_PHONE_NUMBER_ID="your_basic_whatsapp_phone_number_id_here"
export BASIC_WHATSAPP_VERIFY_TOKEN="your_basic_whatsapp_verify_token_here"
export RESEARCH_WHATSAPP_ACCESS_TOKEN="your_research_whatsapp_access_token_here"
export RESEARCH_WHATSAPP_PHONE_NUMBER_ID="your_research_whatsapp_phone_number_id_here"
export RESEARCH_WHATSAPP_VERIFY_TOKEN="your_research_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 multiple_instances.py, then run:

python multiple_instances.py

Route each WhatsApp account to its callback

Keep Python and ngrok running. Follow WhatsApp setup, using your public origin plus /basic/webhook and BASIC_WHATSAPP_VERIFY_TOKEN for the app-level callback, then subscribe the app to the messages field. For this two-interface setup, use two distinct WhatsApp Business Accounts (WABAs) under the same Meta app, with the corresponding phone number and access token for each.

WABA	Callback path	Verification token
Basic account	`/basic/webhook`	`BASIC_WHATSAPP_VERIFY_TOKEN`
Research account	`/web-research/webhook`	`RESEARCH_WHATSAPP_VERIFY_TOKEN`

Configure a separate callback override for each WABA. In Meta's API client, send POST /{WABA-ID}/subscribed_apps with an authorized bearer token and this JSON body, substituting that account's full HTTPS callback and matching verification token:

{
  "override_callback_uri": "https://YOUR-TUNNEL.ngrok-free.app/basic/webhook",
  "verify_token": "YOUR_BASIC_VERIFY_TOKEN"
}

Repeat for the research WABA using /web-research/webhook. Complete each verification challenge. These overrides route messages by WABA; the two Agno prefixes do not inspect metadata.phone_number_id to dispatch a shared callback. Two phone numbers in one WABA need a different routing arrangement.

Add and verify a recipient for Meta test numbers, then message each configured number. Update both overrides whenever the tunnel changes.

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