py-wago

Async Python client library for the Wago WhatsApp API (MultiDevice v8).

Installation

pip install .            # from source
# or
pip install py-wago      # once published

Quick Start

import asyncio
from py_wago import WagoClient

async def main():
    async with WagoClient(
        base_url="https://wago.example.com",
        username="admin",
        password="secret",
        device_id="my-device",           # optional default device
    ) as client:
        # Check connection status
        status = await client.app_status()
        print(status.results.is_connected)

        # Send a text message
        resp = await client.send_message(
            phone="628123456789@s.whatsapp.net",
            message="Hello from py-wago!",
        )
        print(resp.results.message_id)

asyncio.run(main())

Authentication

Every request uses HTTP Basic Auth. Pass username and password when creating the client:

client = WagoClient(
    base_url="https://wago.example.com",
    username="user",
    password="pass",
)

Multi-Device Support

Set a default device_id on the client, or override per-call:

client = WagoClient(
    base_url="https://wago.example.com",
    username="user",
    password="pass",
    device_id="default-device",
)

# Override per-call
await client.send_message(
    phone="628123456789@s.whatsapp.net",
    message="Hello",
    device_id="other-device",
)

Custom Headers

You can pass extra HTTP headers that will be included in every request. This is useful when the API is behind a reverse proxy such as Cloudflare Access or any other service that requires additional authentication headers:

client = WagoClient(
    base_url="https://wago.example.com",
    username="user",
    password="pass",
    custom_headers={
        "CF-Access-Client-Id": "xxx.access",
        "CF-Access-Client-Secret": "my-secret",
    },
)

The headers are merged with the per-request headers (e.g. X-Device-Id), so you can combine custom_headers with device_id without conflicts.

API Coverage

App

Device Management

User

Send

Message

Chat

Group

Newsletter & Chatwoot

Error Handling

from py_wago import WagoClient, WagoBadRequestError, WagoUnauthorizedError

async with WagoClient(...) as client:
    try:
        await client.send_message(phone="invalid", message="hi")
    except WagoBadRequestError as e:
        print(f"Bad request: {e.message}")
    except WagoUnauthorizedError:
        print("Check your credentials")

Exception Hierarchy

WagoError
├── WagoBadRequestError      (400)
├── WagoUnauthorizedError    (401)
├── WagoNotFoundError        (404)
├── WagoConflictError        (409)
├── WagoInternalServerError  (500)
└── WagoConnectionError      (network issues)

Sending Media

# From file path
await client.send_image(
    phone="628123456789@s.whatsapp.net",
    image="/path/to/photo.jpg",
    caption="Check this out!",
)

# From URL
await client.send_image(
    phone="628123456789@s.whatsapp.net",
    image_url="https://example.com/photo.jpg",
    caption="From the web",
)

# From bytes / file object
with open("doc.pdf", "rb") as f:
    await client.send_file(
        phone="628123456789@s.whatsapp.net",
        file=f,
        caption="Important document",
        filename="report.pdf",
    )

Issues

Found a bug or have a feature request? Please open an issue.

License

MIT