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

> Subscribe to WebSocket events with reconnect, ack, and clean shutdown using the Java SDK

Use `client.events()` to receive instance events in real time without exposing a public URL.

For HTTP callbacks, see [Webhooks](/en/sdk/java/webhooks).

## Common events

| Event                     | Description                        |
| ------------------------- | ---------------------------------- |
| `Message`                 | Incoming message or message event. |
| `ReadReceipt`             | Read/delivery update.              |
| `Presence`                | User presence.                     |
| `ChatPresence`            | Chat presence.                     |
| `HistorySync`             | History sync.                      |
| `Connected`               | Instance connected to WhatsApp.    |
| `Disconnected`            | Instance disconnected.             |
| `GroupParticipantsAdd`    | Group participants added.          |
| `GroupParticipantsRemove` | Group participants removed.        |
| `All`                     | All subscribed events.             |

## Subscribe to 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();
}
```

**Return:** `EventSubscription` — object with `on()`, `close()`, and automatic reconnect when configured.

Main `EventSubscribeRequest` options: `instanceId`, `instanceToken`, `event(...)`, `reconnect`, `maxRetries`, `retryDelayMs`, `lastEventId`.

## Register handlers

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

## Close subscription

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

**Return:** `Promise<void>` after the WebSocket closes.

## Event envelope

Each received event uses this JSON shape:

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

## Delivery and ack

Delivery is **at-least-once**. Deduplicate by `event.id()` when handlers have side effects.

Use `lastEventId(...)` when reconnecting to reduce gaps.