whagent¶

whagent is a Python library for the WhatsApp Agent Platform — the API behind the agents you create from WhatsApp's own settings. You write a function that answers a message; the library handles the rest: polling, read receipts, media, retries and rate limits.

from whagent import Agent

agent = Agent("<ACCESS_TOKEN>")

@agent.on_text
def echo(ctx):
    ctx.reply(f"You said: {ctx.text}")

agent.run()

That is a complete agent. It polls for your messages, marks them read, shows a typing indicator while your function runs, and sends the reply.

Installation¶

pip install whagent

Python 3.9 or newer. The only runtime dependency is requests. Upgrade with pip install -U whagent; releases are listed on PyPI.

First, the one rule that shapes everything¶

An agent talks to exactly one person: the WhatsApp account that created it — you.

It cannot message anyone else, cannot message your other agents, and cannot post in groups. It is a private assistant in your own chat list, not a bot with an audience. Why, and what follows from it.

How this documentation is organized¶

Start¶

Getting started — create an agent, get a token, run your first reply
How it works — polling, offsets and identifiers, in six short pieces
Questions and answers — who it can message, what happens offline, running two agents

Guides¶

Sending messages — text, media, captions, quotes, link previews
Receiving messages — the poll loop, and never missing or repeating one
Files and media — download what you are sent, upload what you send back
Receipts and typing — blue ticks and the typing indicator

Reference¶

Agent — handlers, Context, the run loop
Client — one method per endpoint
Models — what Message, Status and Update carry
Errors — every error code, and what to do about it
Rate limits — the per-method caps and the built-in limiter
Limits and formats — sizes, MIME types, codecs

Practice¶

Recipes — persistence, slow work, worker threads, deployment
Testing — testing an agent without touching the network

whagent is an independent library built against version 1 of the developer manual (August 25, 2026). It is not affiliated with or endorsed by WhatsApp.