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

Use `client.Events.SubscribeAsync` para receber eventos realtime da instância.

## Eventos comuns

| Evento                    | Quando ocorre                      |
| ------------------------- | ---------------------------------- |
| `Message`                 | Nova mensagem recebida ou enviada. |
| `ReadReceipt`             | Atualização de leitura.            |
| `Presence`                | Presença de usuário.               |
| `HistorySync`             | Sincronização de histórico.        |
| `ChatPresence`            | Presença em conversa.              |
| `Connected`               | Instância conectada.               |
| `Disconnected`            | Instância desconectada.            |
| `GroupParticipantsAdd`    | Participante adicionado a grupo.   |
| `GroupParticipantsRemove` | Participante removido de grupo.    |
| `All`                     | Handler para todos os eventos.     |

## Assinar 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);
```

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

## Registrar 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);
});
```

## Fechar assinatura

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

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

Use `await using` para garantir fechamento limpo quando o escopo terminar.

## Envelope do evento

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

## Entrega e ack

O SDK envia ack depois que os handlers terminam. A entrega é at-least-once; deduplique pelo `evt.Id` quando o handler tiver efeitos colaterais.

## Realtime ou webhook?

Use realtime para workers, CLIs, dashboards e processos que podem manter conexão WebSocket ativa. Use [webhooks](/pt-BR/sdk/dotnet/webhooks) para integrações server-to-server persistentes.