> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vzaps.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Starter Guide

> Complete Python SDK flow: authenticate, create an instance, subscribe, pair, configure events, and send messages

This guide shows the recommended path from zero to a connected instance sending messages through VZaps.

## 1. Install and create the client

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

```python theme={null}
from vzaps import VZapsClient

with VZapsClient(
    client_token="your-client-token",
    client_secret="your-client-secret",
) as client:
    ...
```

## 2. Validate authentication

```python theme={null}
jwt = client.auth.get_access_token()
print(jwt[:16])
```

In most flows you do not need to call `get_access_token()`. SDK resources do it automatically.

## 3. List existing instances

```python theme={null}
instances = client.instances.list(
    page=1,
    size=20,
    search="support",
)

print(instances)
```

## 4. Create an instance

```python theme={null}
created = client.instances.create(
    name="Sales Support",
    webhook="https://example.com/webhooks/vzaps",
    events_subscribe=["Message", "ReadReceipt", "Connected", "Disconnected"],
)

print(created)
```

Store from the response:

* `id`: instance identifier.
* `token`: instance token. Use it as `instance_token` in instance calls.

## 5. Subscribe the instance

```python theme={null}
subscription = client.instances.subscribe(
    "VZ...",
    {},
    instance_token="instance-token",
)

print(subscription)
```

If a cancellation is scheduled and you want to reactivate the subscription:

```python theme={null}
resumed = client.instances.resume_subscription(
    "VZ...",
    instance_token="instance-token",
)
```

## 6. Pair WhatsApp

Check status:

```python theme={null}
status = client.sessions.status("VZ...", instance_token="instance-token")
print(status)
```

Fetch QR code:

```python theme={null}
qr = client.sessions.qr("VZ...", instance_token="instance-token")
print(qr)
```

Fetch pairing code by phone:

```python theme={null}
pair_code = client.sessions.pair_code(
    "VZ...",
    "5511999999999",
    instance_token="instance-token",
)
print(pair_code)
```

## 7. Configure webhook

See [Webhooks](/en/sdk/python/webhooks) for full configuration, logs, and examples.

```python theme={null}
client.webhooks.set(
    instance_id="VZ...",
    instance_token="instance-token",
    webhook_url="https://example.com/webhooks/vzaps",
    events=["Message", "ReadReceipt", "Connected", "Disconnected"],
)
```

## 8. Subscribe to realtime

See [Realtime](/en/sdk/python/realtime) for subscription details, ack, and reconnection.

```python theme={null}
import asyncio

from vzaps import AsyncVZapsClient

async def main():
    async with AsyncVZapsClient(
        client_token="your-client-token",
        client_secret="your-client-secret",
    ) as client:
        async with client.events.subscribe(
            instance_id="VZ...",
            instance_token="instance-token",
            events=["Message", "Connected", "Disconnected"],
            reconnect=True,
        ) as subscription:

            @subscription.on("Message")
            async def on_message(event):
                print(event.id)
                print(event.data)

            @subscription.on_error
            async def on_error(error):
                print(error)

            await subscription.wait_closed()

asyncio.run(main())
```

## 9. Send the first message

```python theme={null}
client.messages.send_text(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    message="Hello! This message was sent with VZaps.",
)
```

## 10. Send media

Image:

```python theme={null}
client.messages.send_image(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    image="https://example.com/image.jpg",
    caption="Image sent with VZaps",
)
```

Document:

```python theme={null}
client.messages.send_document(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    document="https://example.com/contract.pdf",
    file_name="contract.pdf",
    caption="Here is the contract",
)
```

See [Messages](/en/sdk/python/messages) for all send types and payloads.

## 11. Check queues

See [Queues](/en/sdk/python/queues) to list, remove, and purge queues.

## 12. Handle errors

```python theme={null}
from vzaps.errors import VZapsAuthenticationError, VZapsError, VZapsTimeoutError

try:
    client.messages.send_text(
        instance_id="VZ...",
        instance_token="instance-token",
        phone="5511999999999",
        message="Hello",
    )
except VZapsAuthenticationError:
    print("Invalid credentials")
except VZapsTimeoutError:
    print("Request timed out")
except VZapsError as error:
    print(error.status, error.message, error.details)
    raise
```