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

Layout

src/whatsapp_sdk/
├── __init__.py   public exports
├── client.py     WhatsApp (combines the three API areas) and exchange_code
├── _base.py      request plumbing: auth, appsecret_proof, pagination, media streaming
├── messages.py   messages, media, templates, Flows
├── account.py    phone numbers, profile, QR codes, blocking, calling, groups
├── business.py   business account, analytics, payments, partners, credit lines
├── errors.py     WhatsAppError and retry classification
└── webhooks.py   verify_signature, verify_challenge

Test (from python/): uv run --isolated --no-project --with . python tests/test_whatsapp_sdk.py

License

Apache-2.0