openping-whatsapp

Async Python client for the WhatsApp Business Platform (Meta Graph API, default v26.0). One file, one dependency (httpx).

pip install openping-whatsapp      # or: uv add openping-whatsapp

from whatsapp_sdk import WhatsApp, WhatsAppError, verify_challenge, verify_signature

wa = WhatsApp("ACCESS_TOKEN", waba_id="WABA_ID", phone_number_id="PHONE_NUMBER_ID")

await wa.send_text("15551234567", "Hi")
await wa.send_template_message(to="15551234567", name="hello_world", language="en_US")

try:
    await wa.send_text("15551234567", "Hi")
except WhatsAppError as error:
    if error.retryable:      # never reached Meta, 429, 5xx, or a transient Meta code
        ...                  # safe to send again
    elif error.maybe_sent:   # went out, no answer: may have been delivered
        ...                  # don't resend blindly
    print(error.status_code, error.detail)

async for template in wa.paginate("WABA_ID/message_templates", limit=100):
    ...

# Webhooks
verify_challenge(request.query_params, VERIFY_TOKEN)          # setup handshake
verify_signature(APP_SECRET, raw_body, request.headers.get("X-Hub-Signature-256"))

waba_id / phone_number_id are defaults; every method also takes them as arguments. to accepts a phone number or a business-scoped user ID (BSUID); send(..., recipient_type="group") messages a group. For bulk sends, pass one shared httpx.AsyncClient (WhatsApp(..., client=client)). Pass app_secret= to sign every call with appsecret_proof. Anything not wrapped: await wa.request("GET", "<path>", params=..., json=...).

Coverage

Reference: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/llms.txt

Test: uv run --no-project --with httpx python test_whatsapp_sdk.py

Releasing

1. Bump version in pyproject.toml and push to main.
2. Actions → Release to PyPI & GitHub → Run workflow. It tests, builds, publishes to PyPI, tags vX.Y.Z, and creates a GitHub release.

License

Apache-2.0