Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.wazzapi.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Python SDK

The official Python SDK gives you a typed client for the public WazzAPI surface. Use it to:
  • send direct WhatsApp messages
  • pair SDK usage with the public API for device inventory and sender selection
  • list, create, update, and delete contacts
  • create templates and preview rendered content
  • verify signed WazzAPI webhook deliveries

Package

Install the published package from PyPI.

Source code

Browse the SDK repository, examples, and release history.

​
Requirements

  • Python 3.10+
  • a WazzAPI account
  • a WazzAPI API key
If you plan to verify webhooks, also create a webhook secret in the dashboard.

​
Install

Choose the package manager that fits your stack:
pip
pip install wazzapi
uv
uv add wazzapi

​
Configuration

The SDK uses https://api.wazzapi.com by default. For most integrations, you only need:
  • WAZZAPI_API_KEY
For webhook verification, also set:
  • WAZZAPI_WEBHOOK_SECRET
.env
WAZZAPI_API_KEY=wz_live_your_api_key
WAZZAPI_WEBHOOK_SECRET=whsec_your_webhook_secret
Keep secrets on the server side only. Do not expose them in browsers or mobile apps.

​
Quick start

​
Send a message

from wazzapi import SendMessageRequest, WazzapiClient

with WazzapiClient(api_key="your-api-key") as client:
    response = client.messages.send(
        SendMessageRequest(
            phone_number="+6281234567890",
            whatsapp_account_id="your-whatsapp-account-id",
            content="Hello from WazzAPI!",
        )
    )

print(response.model_dump())

​
List contacts

from wazzapi import WazzapiClient

with WazzapiClient(api_key="your-api-key") as client:
    response = client.contacts.list(limit=20, search="alice")

for contact in response.contacts:
    print(contact.model_dump())

### Create a template

```python
from wazzapi import TemplateCreateRequest, WazzapiClient

with WazzapiClient(api_key="your-api-key") as client:
    template = client.templates.create(
        TemplateCreateRequest(
            name="welcome-message",
            category="marketing",
            content="Hi {{name}}, welcome to WazzAPI!",
        )
    )

print(template.model_dump())

​
Preview a template

from wazzapi import TemplatePreviewRequest, WazzapiClient

with WazzapiClient(api_key="your-api-key") as client:
    preview = client.templates.preview(
        TemplatePreviewRequest(
            content="Hi {{name}}, your code is {{code}}.",
            custom_variables={"name": "Alice", "code": "WZ-1234"},
        )
    )

print(preview.model_dump())

​
Verify incoming webhooks

Use WebhookHandler to validate the raw request body against the signature header before parsing JSON. 
from wazzapi import WebhookHandler

handler = WebhookHandler("your-webhook-secret")
webhook = handler.verify_and_parse(raw_body, request.headers)

print(webhook.event_type)
print(webhook.data.model_dump())
WazzAPI signs webhook deliveries with:
  • X-Wazzapi-Signature
  • X-Wazzapi-Event
  • X-Wazzapi-Event-ID
Supported event families include:
  • message events: message.received, message.sent, message.delivered, message.read, message.failed
  • device events: device.connected, device.disconnected

​
Handle API errors

When the API returns a non-success status, the SDK raises WazzapiAPIError. 
from wazzapi import WazzapiAPIError, WazzapiClient

try:
    with WazzapiClient(api_key="your-api-key") as client:
        client.messages.get("missing-message-id")
except WazzapiAPIError as exc:
    print(exc.status_code)
    print(exc.message)

​
Example scripts

The SDK repository includes ready-to-run examples:
  • examples/send_message.py
  • examples/list_contacts.py
  • examples/create_template.py
  • examples/preview_template.py
  • examples/verify_webhook.py

​
Next steps

Quickstart

Create your API key and send your first live request.

API Reference

Explore endpoints and payloads behind the SDK methods.