> ## 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 TypeScript: 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}
npm install @vzaps/sdk
```

```ts theme={null}
import { VZapsClient } from '@vzaps/sdk';

const vzaps = new VZapsClient({
  clientToken: process.env.VZAPS_CLIENT_TOKEN!,
  clientSecret: process.env.VZAPS_CLIENT_SECRET!,
});
```

## 2. Valide autenticação

```ts theme={null}
const jwt = await vzaps.auth.getAccessToken();
console.log(jwt.slice(0, 16));
```

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

## 3. Liste instâncias existentes

```ts theme={null}
const instances = await vzaps.instances.list({
  page: 1,
  pageSize: 20,
  search: 'atendimento',
});

console.dir(instances, { depth: null });
```

## 4. Crie uma instância

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

console.dir(created, { depth: null });
```

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

```ts theme={null}
const subscription = await vzaps.instances.subscribe(
  'VZ...',
  {},
  { instanceToken: 'instance-token' },
);

console.dir(subscription, { depth: null });
```

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

```ts theme={null}
const resumed = await vzaps.instances.resumeSubscription('VZ...', {
  instanceToken: 'instance-token',
});
```

## 6. Pareie o WhatsApp

Consultar status:

```ts theme={null}
const status = await vzaps.sessions.status('VZ...', {
  instanceToken: 'instance-token',
});

console.dir(status, { depth: null });
```

Buscar QR code:

```ts theme={null}
const qr = await vzaps.sessions.qr('VZ...', {
  instanceToken: 'instance-token',
});

console.dir(qr, { depth: null });
```

Buscar código de pareamento por telefone:

```ts theme={null}
const pairCode = await vzaps.sessions.pairCode('VZ...', '5511999999999', {
  instanceToken: 'instance-token',
});

console.dir(pairCode, { depth: null });
```

## 7. Configure webhook

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

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

## 8. Assine realtime

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

```ts theme={null}
const subscription = await vzaps.events.subscribe({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  events: ['Message', 'Connected', 'Disconnected'],
  reconnect: true,
});

subscription.on('Message', (event) => {
  console.log(event.id);
  console.dir(event.data, { depth: null });
});

subscription.on('error', (error) => {
  console.error(error);
});
```

## 9. Envie a primeira mensagem

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

## 10. Envie mídia

Imagem:

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

Documento:

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

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

## 11. Acompanhe filas

Veja [Filas](/pt-BR/sdk/typescript/queues) para listar, remover e limpar filas.

## 12. Trate erros

```ts theme={null}
import {
  VZapsAuthenticationError,
  VZapsError,
  VZapsTimeoutError,
} from '@vzaps/sdk';

try {
  await vzaps.messages.sendText({
    instanceId: 'VZ...',
    instanceToken: 'instance-token',
    phone: '5511999999999',
    message: 'Olá',
  });
} catch (error) {
  if (error instanceof VZapsAuthenticationError) {
    console.error('Credenciais inválidas');
  } else if (error instanceof VZapsTimeoutError) {
    console.error('Request expirou');
  } else if (error instanceof VZapsError) {
    console.error(error.status, error.message, error.details);
  }

  throw error;
}
```