client.events com AsyncVZapsClient para receber eventos da instância em tempo real sem expor uma URL pública.
Para callbacks HTTP, veja Webhooks.
Eventos comuns
| Evento | Descrição |
|---|---|
Message | Nova mensagem recebida ou evento de mensagem. |
ReadReceipt | Atualização de leitura/entrega. |
Presence | Presença do usuário. |
ChatPresence | Presença no chat. |
HistorySync | Sincronização de histórico. |
Connected | Instância conectada ao WhatsApp. |
Disconnected | Instância desconectada. |
GroupParticipantsAdd | Participantes adicionados ao grupo. |
GroupParticipantsRemove | Participantes removidos do grupo. |
All | Todos os eventos inscritos. |
Assinar o realtime
EventSubscription — objeto com on(), close() e reconexao automatica quando configurada.
Opções:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
instance_id | string | Sim | Instância a observar. |
instance_token | string | Sim | Token da instância. |
events | list[str] | Não | Lista de eventos. Se omitido, usa os eventos inscritos na instância. |
reconnect | boolean | Não | Reconecta automaticamente. Padrão: True. |
max_retries | number | Não | Máximo de tentativas de reconexão. |
retry_delay_seconds | number | Não | Atraso base entre tentativas. |
last_event_id | string | Não | Cursor para retomar consumo. |
Registrar handlers
Fechar assinatura
Promise<void> apos fechar o WebSocket.
Em processos de longa duração, feche no shutdown:
Envelope do evento
Cada evento recebido pelo SDK tem esta forma:| Campo | Descrição |
|---|---|
id | Identificador do evento. Use para deduplicação. |
type | Tipo do evento. |
instance_id | Instância de origem. |
created_at | Data de criação do evento. |
data | Payload do evento. |
data.media_url | URL da mídia quando o evento recebido contém mídia e a plataforma fornece o arquivo. |
Entrega e ack
A entrega é at-least-once. Sua app deve processar eventos de forma idempotente. Após o handler terminar, o SDK envia o ack automaticamente. Recomendações:- guarde
event.idse sua automação executa efeitos externos; - ignore eventos já processados;
- use
last_event_idao reconectar para reduzir lacunas; - mantenha handlers rápidos e mova trabalho longo para sua própria fila.
Realtime ou webhook?
| Cenário | Recomendação |
|---|---|
| Bot, dashboard ou app com consumo imediato | Realtime |
| Backend com URL pública e pipeline HTTP | Webhook |
| Não quer expor URL pública | Realtime |
| Precisa reprocessar entregas via logs | Webhook |

