WhatsApp - Upsonic AI

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

Setup

Required environment variables:

WHATSAPP_VERIFY_TOKEN (for webhook verification)
WHATSAPP_ACCESS_TOKEN (required by WhatsAppTools for sending messages)
WHATSAPP_PHONE_NUMBER_ID (required by WhatsAppTools for sending messages)
Optional (production): WHATSAPP_APP_SECRET (for webhook signature validation)

Operating Modes

TASK (default) – Each message is processed as an independent task; no conversation history. Best for one-off queries and stateless bots.
CHAT – Messages from the same sender share a conversation session. The agent remembers context. Best for conversational and support use cases.

Heartbeat

When used with an AutonomousAgent that has heartbeat=True, the interface periodically sends the agent’s heartbeat_message to the agent, then delivers the response to the WhatsApp recipient. The target recipient is resolved automatically from the first incoming message. You can also set it explicitly via heartbeat_recipient.

import os
from upsonic import AutonomousAgent
from upsonic.interfaces import InterfaceManager, WhatsAppInterface

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-6",
    name="WhatsAppBot",
    heartbeat=True,
    heartbeat_period=30,
    heartbeat_message="Summarize any new updates.",
)

whatsapp = WhatsAppInterface(
    agent=agent,
    verify_token=os.getenv("WHATSAPP_VERIFY_TOKEN"),
    app_secret=os.getenv("WHATSAPP_APP_SECRET"),
    mode="chat",
    # heartbeat_recipient="905551234567",  # optional explicit override
)

manager = InterfaceManager(interfaces=[whatsapp])

if __name__ == "__main__":
    manager.serve(host="0.0.0.0", port=8000)

Reset Command (CHAT mode only)

In CHAT mode, senders can clear their conversation by sending the reset command (e.g. /reset) as a message. Configure it with reset_command; set to None to disable. If the agent has a workspace configured, the reset command will also trigger a dynamic greeting message based on the workspace configuration. See Workspace for details.

Access Control (Whitelist)

Pass allowed_numbers (list of phone numbers in international format, e.g. ["905551234567"]). Only those numbers are processed; others receive “This operation not allowed”. Omit allowed_numbers (or set None) to allow all senders.

Example Usage

Create an agent, expose it with the WhatsAppInterface interface, and serve via InterfaceManager. Example with CHAT mode, reset command, and optional whitelist:

import os
from upsonic import Agent
from upsonic.interfaces import InterfaceManager, WhatsAppInterface, InterfaceMode

agent = Agent(
    model="anthropic/claude-sonnet-4-6",
    name="WhatsAppBot",
)

whatsapp = WhatsAppInterface(
    agent=agent,
    verify_token=os.getenv("WHATSAPP_VERIFY_TOKEN"),
    app_secret=os.getenv("WHATSAPP_APP_SECRET"),
    mode=InterfaceMode.CHAT,
    reset_command="/reset",
    allowed_numbers=["905551234567", "14155551234"],
)

manager = InterfaceManager(interfaces=[whatsapp])

if __name__ == "__main__":
    manager.serve(host="0.0.0.0", port=8000, reload=False)

Core Components

WhatsAppInterface (interface): Wraps an Upsonic Agent for WhatsApp via FastAPI.
InterfaceManager.serve: Serves the FastAPI app using Uvicorn.

`WhatsAppInterface` Interface

Main entry point for Upsonic WhatsApp applications.

Initialization Parameters

Parameter	Type	Default	Description
`agent`	`Agent`	Required	Upsonic `Agent` instance.
`verify_token`	`Optional[str]`	`None`	WhatsApp webhook verification token (or set `WHATSAPP_VERIFY_TOKEN`).
`app_secret`	`Optional[str]`	`None`	WhatsApp app secret for signature validation (or set `WHATSAPP_APP_SECRET`).
`name`	`str`	`"WhatsApp"`	Interface name.
`mode`	`Union[InterfaceMode, str]`	`InterfaceMode.TASK`	`TASK` or `CHAT`.
`reset_command`	`Optional[str]`	`"/reset"`	Message text that resets chat session (CHAT mode). Set `None` to disable.
`storage`	`Optional[Storage]`	`None`	Storage backend for chat sessions (CHAT mode).
`allowed_numbers`	`Optional[List[str]]`	`None`	Whitelist of phone numbers (e.g. `"905551234567"`). `None` = allow all.
`heartbeat_recipient`	`Optional[str]`	`None`	Explicit WhatsApp phone number for heartbeat delivery. Auto-detected from first incoming message if omitted.

Key Methods

Method	Parameters	Return Type	Description
`attach_routes`	None	`APIRouter`	Returns the FastAPI router and attaches endpoints.
`is_user_allowed`	`sender: str`	`bool`	Whether the sender number is in the whitelist (or whitelist disabled).

Endpoints

Mounted under the /whatsapp prefix:

`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); skipped if WHATSAPP_APP_SECRET not configured.
Processes text, image, video, audio, and document messages via the agent.
Sends replies (splits long messages; uploads and sends generated images).
Responses: 200 {"status": "processing"}, 200 {"status": "ignored"}, or 200 {"status": "invalid_payload"}, 403 invalid signature, 500 errors.

`GET /whatsapp/health`

Health/status of the interface.

​Setup

​Operating Modes

​Heartbeat

​Reset Command (CHAT mode only)

​Access Control (Whitelist)

​Example Usage

​Core Components

​WhatsAppInterface Interface

​Initialization Parameters

​Key Methods

​Endpoints

​GET /whatsapp/webhook

​POST /whatsapp/webhook

​GET /whatsapp/health