> ## 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 through the .NET SDK

Use `client.Events.SubscribeAsync` to receive realtime events from an instance.

## Common events

| Event                     | When it happens                   |
| ------------------------- | --------------------------------- |
| `Message`                 | New incoming or outgoing message. |
| `ReadReceipt`             | Read status update.               |
| `Presence`                | User presence.                    |
| `HistorySync`             | History synchronization.          |
| `ChatPresence`            | Conversation presence.            |
| `Connected`               | Instance connected.               |
| `Disconnected`            | Instance disconnected.            |
| `GroupParticipantsAdd`    | Participant added to a group.     |
| `GroupParticipantsRemove` | Participant removed from a group. |
| `All`                     | Handler for every event.          |

## Subscribe to realtime

```csharp theme={null}
await using var subscription = await client.Events.SubscribeAsync(
    new VZapsEventSubscribeRequest
    {
        InstanceId = "VZ...",
        InstanceToken = "instance-token",
        Events = new[] { VZapsEventType.Message, VZapsEventType.Connected },
        Reconnect = true,
        MaxRetries = 10,
        LastEventId = "evt_123",
    },
    cancellationToken);
```

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

## Register handlers

```csharp theme={null}
subscription.On(VZapsEventType.Message, async evt =>
{
    Console.WriteLine(evt.Id);
    await Task.CompletedTask;
});

subscription.On(VZapsEventType.All, evt =>
{
    Console.WriteLine(evt.Type);
});
```

## Close subscription

```csharp theme={null}
await subscription.WaitForCloseAsync(cancellationToken);
```

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

Use `await using` to ensure clean shutdown when the scope ends.

## Event envelope

```csharp theme={null}
public sealed class VZapsEvent
{
    public string Id { get; set; }
    public string Type { get; set; }
    public string InstanceId { get; set; }
    public DateTimeOffset? CreatedAt { get; set; }
    public JsonElement Data { get; set; }
}
```

## Delivery and ack

The SDK sends ack after handlers complete. Delivery is at-least-once; deduplicate by `evt.Id` when handlers have side effects.

## Realtime or webhook?

Use realtime for workers, CLIs, dashboards, and processes that can keep an active WebSocket connection. Use [webhooks](/en/sdk/dotnet/webhooks) for persistent server-to-server integrations.