whatsloon

Python SDK for the WhatsApp Cloud API — sync + async, typed, tested.

Overview

whatsloon wraps the WhatsApp Cloud API (graph.facebook.com) with composable mixins for every message type: text, image, video, audio, document, sticker, reaction, location, contacts, templates, interactive lists / reply buttons / CTA / flows, typing indicators, and read receipts.

• Sync via requests, async via httpx
• Validated payload builders with WhatsApp API limits
• {"success": bool, "data" | "error"} result shape + logging
• Full test suite, typed package (py.typed), docs on GitHub Pages

Installation

pip install whatsloon

Requires Python >=3.9.

Quickstart

New code should use the v3 client (WhatsApp with per-send to=, typed models, retries, observability) — see the messages guide. Below is the frozen 2.x API (critical fixes only).

from whatsloon import WhatsAppCloudAPIClient

client = WhatsAppCloudAPIClient(
    access_token="YOUR_API_KEY",
    phone_number_id="phone_number_id",
    recipient_country_code="91",
    recipient_mobile_number="9876543210",
)

result = client.send_text_message("Hello, world!", preview_url=True)
print(result)

Async:

import asyncio
from whatsloon import WhatsAppCloudAPIClient


async def main():
    client = WhatsAppCloudAPIClient(
        access_token="YOUR_API_KEY",
        phone_number_id="phone_number_id",
        recipient_country_code="91",
        recipient_mobile_number="9876543210",
    )
    print(await client.async_send_text_message("Hello async!"))


asyncio.run(main())

Custom client with only needed features:

from whatsloon import WhatsAppBaseClient, TextSender, ImageSender


class MyClient(WhatsAppBaseClient, TextSender, ImageSender):
    pass

See docs/quickstart.md, docs/usage.md, and examples/ for more.

Full docs: https://maharanasarkar.github.io/whatsloon/

Features

• Text, image, video, audio, document, sticker
• Interactive: lists, reply buttons, CTA, flows
• Location + location request, contacts, address
• Templates with components, reactions, typing indicators, read receipts
• Sync + async for every sender

Development

git clone https://github.com/maharanasarkar/whatsloon.git
cd whatsloon
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install
pytest
ruff check .
ruff format --check .
mypy whatsloon
python -m build

See CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md.

Testing

pip install -e ".[test]"
pytest
pytest --cov=whatsloon tests/

Changelog

See CHANGELOG.md. Releases are cut from tags v* via Trusted Publishing to PyPI.

License

MIT — see LICENSE.