> ## 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 PHP 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}
composer require vzaps/sdk
```

```php theme={null}
require __DIR__ . '/vendor/autoload.php';

use VZaps\Sdk\VZapsClient;

$vzaps = new VZapsClient(
    clientToken: getenv('VZAPS_CLIENT_TOKEN'),
    clientSecret: getenv('VZAPS_CLIENT_SECRET'),
);
```

## 2. Validate authentication

```php theme={null}
$jwt = $vzaps->auth()->getAccessToken();
echo substr($jwt, 0, 16) . PHP_EOL;
```

In most flows, you do not need to call `getAccessToken()`. SDK resources do that automatically.

## 3. List existing instances

```php theme={null}
$instances = $vzaps->instances()->list([
    'page' => 1,
    'pageSize' => 20,
    'search' => 'support',
]);

print_r($instances);
```

## 4. Create an instance

```php theme={null}
$created = $vzaps->instances()->create([
    'name' => 'Commercial Support',
    'webhook' => 'https://example.com/webhooks/vzaps',
    'eventsSubscribe' => ['Message', 'ReadReceipt', 'Connected', 'Disconnected'],
]);

print_r($created);
```

Save from the response:

* `id`: instance identifier.
* `token`: instance token. Use it as `instanceToken` on instance calls.

## 5. Subscribe the instance

```php theme={null}
$subscription = $vzaps->instances()->subscribe(
    'VZ...',
    [],
    'instance-token',
);

print_r($subscription);
```

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

```php theme={null}
$resumed = $vzaps->instances()->resumeSubscription(
    'VZ...',
    'instance-token',
);
```

## 6. Pair WhatsApp

Check status:

```php theme={null}
$status = $vzaps->sessions()->status('VZ...', 'instance-token');

print_r($status);
```

Fetch QR code:

```php theme={null}
$qr = $vzaps->sessions()->qr('VZ...', 'instance-token');

print_r($qr);
```

Fetch phone pairing code:

```php theme={null}
$pairCode = $vzaps->sessions()->pairCode(
    'VZ...',
    '5511999999999',
    'instance-token',
);

print_r($pairCode);
```

## 7. Configure webhook

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

```php theme={null}
$vzaps->webhooks()->set([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'webhookURL' => 'https://example.com/webhooks/vzaps',
    'events' => ['Message', 'ReadReceipt', 'Connected', 'Disconnected'],
]);
```

## 8. Subscribe to realtime

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

```php theme={null}
use VZaps\Sdk\Models\Realtime\EventSubscribeRequest;
use VZaps\Sdk\Models\Realtime\VZapsEventType;

$subscription = $vzaps->events()->subscribe(new EventSubscribeRequest(
    instanceId: 'VZ...',
    instanceToken: 'instance-token',
    events: [VZapsEventType::Message, VZapsEventType::Connected, VZapsEventType::Disconnected],
    reconnect: true,
));

$subscription->on(VZapsEventType::Message, function ($event): void {
    echo $event->id . PHP_EOL;
    print_r($event->data);
});

$subscription->onError(function ($error): void {
    error_log((string) $error);
});
```

## 9. Send the first message

```php theme={null}
$vzaps->messages()->sendText([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'message' => 'Hello! This message was sent through VZaps.',
]);
```

## 10. Send media

Image:

```php theme={null}
$vzaps->messages()->sendImage([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'image' => 'https://example.com/image.jpg',
    'caption' => 'Image sent through VZaps',
]);
```

Document:

```php theme={null}
$vzaps->messages()->sendDocument([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'document' => 'https://example.com/contract.pdf',
    'fileName' => 'contract.pdf',
    'caption' => 'Here is the contract',
]);
```

See [Messages](/en/sdk/php/messages) for every send type and payload.

## 11. Check queues

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

## 12. Handle errors

```php theme={null}
use VZaps\Sdk\Exceptions\VZapsApiException;
use VZaps\Sdk\Exceptions\VZapsAuthenticationException;
use VZaps\Sdk\Exceptions\VZapsException;
use VZaps\Sdk\Exceptions\VZapsTimeoutException;

try {
    $vzaps->messages()->sendText([
        'instanceId' => 'VZ...',
        'instanceToken' => 'instance-token',
        'phone' => '5511999999999',
        'message' => 'Hello',
    ]);
} catch (VZapsAuthenticationException $error) {
    error_log('Invalid credentials');
} catch (VZapsTimeoutException $error) {
    error_log('Request timed out');
} catch (VZapsApiException $error) {
    error_log($error->statusCode . ' ' . $error->getMessage());
    print_r($error->details);
} catch (VZapsException $error) {
    error_log($error->getMessage());
}
```