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

# Realtime

> Como receber eventos em tempo real com o SDK TypeScript via WebSocket

Use `vzaps.events` para receber eventos da instância em tempo real, sem expor URL pública.

Para callbacks HTTP, veja [Webhooks](/pt-BR/sdk/typescript/webhooks).

## Eventos comuns

| Evento                    | Descrição                                     |
| ------------------------- | --------------------------------------------- |
| `Message`                 | Nova mensagem recebida ou evento de mensagem. |
| `ReadReceipt`             | Atualização de leitura/entrega.               |
| `Presence`                | Presença do usuário.                          |
| `ChatPresence`            | Presença em chat.                             |
| `HistorySync`             | Sincronização de histórico.                   |
| `Connected`               | Instância conectada ao WhatsApp.              |
| `Disconnected`            | Instância desconectada.                       |
| `GroupParticipantsAdd`    | Participantes adicionados em grupo.           |
| `GroupParticipantsRemove` | Participantes removidos de grupo.             |
| `All`                     | Todos os eventos assinados.                   |

## Assinar realtime

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

**Retorno:** `EventSubscription` — objeto com `on()`, `close()` e reconexao automatica quando configurada.

Opções:

| Campo           | Tipo               | Obrigatório | Descrição                                                         |
| --------------- | ------------------ | ----------- | ----------------------------------------------------------------- |
| `instanceId`    | `string`           | Sim         | Instância que será acompanhada.                                   |
| `instanceToken` | `string`           | Sim         | Token da instância.                                               |
| `events`        | `VZapsEventType[]` | Não         | Lista de eventos. Se omitido, usa eventos assinados na instância. |
| `reconnect`     | `boolean`          | Não         | Reconectar automáticamente. Padrão: `true`.                       |
| `maxRetries`    | `number`           | Não         | Máximo de tentativas.                                             |
| `retryDelayMs`  | `number`           | Não         | Delay entre tentativas.                                           |
| `lastEventId`   | `string`           | Não         | Cursor para retomada.                                             |
| `signal`        | `AbortSignal`      | Não         | Fechar assinatura quando abortar.                                 |

## Registrar handlers

```ts theme={null}
subscription.on('open', () => {
  console.log('Realtime conectado');
});

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

subscription.on('All', (event) => {
  console.log('Evento recebido:', event.type);
});

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

## Fechar assinatura

```ts theme={null}
await subscription.close();
```

**Retorno:** `Promise<void>` apos fechar o WebSocket.

Em processos Node.js:

```ts theme={null}
process.on('SIGINT', async () => {
  await subscription.close();
  process.exit(0);
});
```

## Envelope do evento

Cada evento recebido pelo SDK tem este formato:

```json theme={null}
{
  "id": "evt_01J...",
  "type": "Message",
  "instance_id": "VZ...",
  "created_at": "2026-06-23T22:57:17.000Z",
  "data": {
    "type": "Message",
    "media_url": "https://cdn.example.com/media/image.jpg"
  }
}
```

Campos:

| Campo            | Descrição                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------------ |
| `id`             | Identificador do evento. Use para deduplicação.                                            |
| `type`           | Tipo do evento.                                                                            |
| `instance_id`    | Instância origem.                                                                          |
| `created_at`     | Data de criação do evento.                                                                 |
| `data`           | Payload do evento.                                                                         |
| `data.media_url` | URL de mídia quando o evento recebido contém mídia e a plataforma disponibiliza o arquivo. |

## Entrega e ack

A entrega é **at-least-once**. Seu app deve tratar eventos de forma idempotente.

Depois que o handler termina, o SDK envia ack automáticamente.

Recomendações:

* salve `event.id` se sua automação executa efeitos externos;
* ignore eventos já processados;
* use `lastEventId` ao reconectar se quiser reduzir lacunas;
* mantenha handlers rápidos e mova trabalhos longos para sua própria fila.

## Realtime ou webhook?

| Cenário                                    | Recomendação |
| ------------------------------------------ | ------------ |
| Bot, dashboard ou app com consumo imediato | Realtime     |
| Backend com URL pública e pipeline HTTP    | Webhook      |
| Não quer expor URL pública                 | Realtime     |
| Quer reprocessar entregas via logs         | Webhook      |