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

> Assine eventos WebSocket com reconnect, ack e fechamento limpo pelo SDK Java

Use `client.events()` para receber eventos da instancia em tempo real, sem expor URL publica.

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

## Eventos comuns

| Evento                    | Descricao                                     |
| ------------------------- | --------------------------------------------- |
| `Message`                 | Nova mensagem recebida ou evento de mensagem. |
| `ReadReceipt`             | Atualizacao de leitura/entrega.               |
| `Presence`                | Presenca do usuario.                          |
| `ChatPresence`            | Presenca em chat.                             |
| `HistorySync`             | Sincronizacao de historico.                   |
| `Connected`               | Instancia conectada ao WhatsApp.              |
| `Disconnected`            | Instancia desconectada.                       |
| `GroupParticipantsAdd`    | Participantes adicionados em grupo.           |
| `GroupParticipantsRemove` | Participantes removidos de grupo.             |
| `All`                     | Todos os eventos assinados.                   |

## Assinar realtime

```java theme={null}
try (var subscription = client.events().subscribe(EventSubscribeRequest.builder()
    .instanceId(instanceId)
    .instanceToken(instanceToken)
    .event(VZapsEventType.MESSAGE)
    .event(VZapsEventType.CONNECTED)
    .reconnect(true)
    .build())) {

  subscription.on(VZapsEventType.MESSAGE, event -> {
    System.out.println(event.id());
    System.out.println(event.instanceId());
  });

  subscription.awaitClose();
}
```

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

Opcoes principais em `EventSubscribeRequest`: `instanceId`, `instanceToken`, `event(...)`, `reconnect`, `maxRetries`, `retryDelayMs`, `lastEventId`.

## Registrar handlers

```java theme={null}
subscription.on(VZapsEventType.MESSAGE, event -> {
  System.out.println(event.id());
});
```

## Fechar assinatura

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

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

## Envelope do evento

Cada evento recebido tem este formato JSON:

```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"
  }
}
```

## Entrega e ack

A entrega e **at-least-once**. Deduplique por `event.id()` quando handlers tiverem efeitos colaterais.

Use `lastEventId(...)` ao reconectar para reduzir lacunas.