Skip to main content
Use client.events() to receive instance events in real time without exposing a public URL. For HTTP callbacks, see Webhooks.

​
Common events

EventDescription
MessageIncoming message or message event.
ReadReceiptRead/delivery update.
PresenceUser presence.
ChatPresenceChat presence.
HistorySyncHistory sync.
ConnectedInstance connected to WhatsApp.
DisconnectedInstance disconnected.
GroupParticipantsAddGroup participants added.
GroupParticipantsRemoveGroup participants removed.
AllAll subscribed events.

​
Subscribe to realtime

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

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

​
Close subscription

subscription.close();
Return: Promise<void> after the WebSocket closes.

​
Event envelope

Each received event uses this JSON shape: 
{
  "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.