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.

Documentation

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

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

143 tests, no network: the HTTP session is faked, so they assert the exact requests the library builds against the payloads in the manual.

License

MIT