> ## 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

> Install and use the official wazzapi Python SDK for messages, contacts, templates, and webhook verification

# 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

<CardGroup cols={2}>
  <Card title="Package" icon="box" href="https://pypi.org/project/wazzapi/">
    Install the published package from PyPI.
  </Card>

  <Card title="Source code" icon="github" href="https://github.com/wazzapihq/wazzapi-py">
    Browse the SDK repository, examples, and release history.
  </Card>
</CardGroup>

## 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:

```bash pip theme={null}
pip install wazzapi
```

```bash uv theme={null}
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`

```bash .env theme={null}
WAZZAPI_API_KEY=wz_live_your_api_key
WAZZAPI_WEBHOOK_SECRET=whsec_your_webhook_secret
```

<Note>
  Keep secrets on the server side only. Do not expose them in browsers or mobile apps.
</Note>

## Quick start

### Send a message

```python theme={null}
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

````python theme={null}
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

```python theme={null}
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.

```python theme={null}
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`.

```python theme={null}
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

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/quickstart">
    Create your API key and send your first live request.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore endpoints and payloads behind the SDK methods.
  </Card>
</CardGroup>