whagent

A small Python library for the WhatsApp Agent Platform API (https://api.whatsapp.com/agent/v1).

It covers every endpoint in version 1 of the developer manual — sending, long-poll receiving, read receipts, the typing indicator and media — and adds what you would otherwise write yourself: typed responses, offset tracking, retries with backoff, client-side rate limiting and local validation against the documented caps.

from whagent import Agent

agent = Agent("<ACCESS_TOKEN>")

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

agent.run()

Install

pip install whagent

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

Documentation

https://elimeshi1.github.io/Whagent/ — built from docs/ with MkDocs Material.

Getting started	Create an agent, get a token, run your first reply
How it works	Polling, offsets, identifiers — the model in six pieces
Questions and answers	Who it can message, what happens offline, running two agents
Sending messages	POST /messages — every type, captions, quotes
Receiving messages	GET /updates and offsets
Files and media	Upload, download, delete
Receipts and typing	POST /statuses
Agent	Handlers, Context, the run loop
Client	One method per endpoint
Models	Update, Message, Status, Media
Errors	Exception hierarchy, codes, retry policy
Rate limits	Per-method caps and the built-in limiter
Limits and formats	Length caps, sizes, accepted MIME types
Recipes	Persistence, slow work, shutdown, deployment
Testing	Testing an agent without touching the network

Build the site locally with:

pip install -r docs/requirements.txt
mkdocs serve

At a glance

Two layers — use whichever fits.

Agent registers handlers and runs the loop for you:

@agent.on_text(r"^/help")     # regex filter
def help_command(ctx):
    ctx.reply("Send me a photo and I'll tell you how big it is.")

@agent.on_message("image")
def on_image(ctx):
    data = ctx.download()
    ctx.reply(f"{len(data)} bytes, thanks {ctx.profile_name or 'there'}!")

Client is one method per endpoint:

from whagent import Client

with Client(token) as client:
    client.send_text("Hello!")                  # an agent has exactly one recipient
    client.send_image(file="cat.jpg", caption="look at this")
    update = client.get_updates(offset=1287, timeout=25)

Examples

• examples/echo_bot.py — text, media and reactions
• examples/media_bot.py — download an attachment, send a file back
• examples/raw_client.py — the loop without the Agent layer

Tests

git clone https://github.com/Elimeshi1/Whagent.git
cd Whagent
pip install -U pip        # editable installs need pip 21.3 or newer
pip install -e ".[dev]"
pytest

License

MIT