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

> Fluxo completo com o SDK PHP: autenticar, criar instância, assinar, parear, configurar eventos e enviar mensagens

Este guia mostra o caminho recomendado para sair do zero até uma instância conectada enviando mensagens pela VZaps.

## 1. Instale e crie o cliente

```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. Valide autenticação

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

Na maioria dos fluxos, você não precisa chamar `getAccessToken()`. Os recursos do SDK fazem isso automaticamente.

## 3. Liste instâncias existentes

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

print_r($instances);
```

## 4. Crie uma instância

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

print_r($created);
```

Guarde do response:

* `id`: identificador da instância.
* `token`: token da instância. Use como `instanceToken` nas chamadas da instância.

## 5. Assine a instância

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

print_r($subscription);
```

Se houver um cancelamento agendado e você quiser reativar a assinatura:

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

## 6. Pareie o WhatsApp

Consultar status:

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

print_r($status);
```

Buscar QR code:

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

print_r($qr);
```

Buscar código de pareamento por telefone:

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

print_r($pairCode);
```

## 7. Configure webhook

Vejá [Webhooks](/pt-BR/sdk/php/webhooks) para configuração completa, logs e exemplos.

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

## 8. Assine realtime

Vejá [Realtime](/pt-BR/sdk/php/realtime) para detalhes de assinatura, ack e reconexão.

```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. Envie a primeira mensagem

```php theme={null}
$vzaps->messages()->sendText([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'message' => 'Olá! Esta mensagem foi enviada pela VZaps.',
]);
```

## 10. Envie mídia

Imagem:

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

Documento:

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

Vejá [Mensagens](/pt-BR/sdk/php/messages) para todos os tipos de envio e payloads.

## 11. Acompanhe filas

Vejá [Filas](/pt-BR/sdk/php/queues) para listar, remover e limpar filas.

## 12. Trate erros

```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' => 'Olá',
    ]);
} catch (VZapsAuthenticationException $error) {
    error_log('Credenciais inválidas');
} catch (VZapsTimeoutException $error) {
    error_log('Request expirou');
} catch (VZapsApiException $error) {
    error_log($error->statusCode . ' ' . $error->getMessage());
    print_r($error->details);
} catch (VZapsException $error) {
    error_log($error->getMessage());
}
```