Realtime - VZaps Docs

Use vzaps.events para receber eventos da instância em tempo real, sem expor 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 em chat.
`HistorySync`	Sincronização de histórico.
`Connected`	Instância conectada ao WhatsApp.
`Disconnected`	Instância desconectada.
`GroupParticipantsAdd`	Participantes adicionados em grupo.
`GroupParticipantsRemove`	Participantes removidos de grupo.
`All`	Todos os eventos assinados.

Assinar realtime

const subscription = await vzaps.events.subscribe({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  events: ['Message', 'ReadReceipt', 'Connected', 'Disconnected'],
  reconnect: true,
  maxRetries: 10,
  retryDelayMs: 1000,
});

Retorno: EventSubscription — objeto com on(), close() e reconexao automatica quando configurada. Opções:

Campo	Tipo	Obrigatório	Descrição
`instanceId`	`string`	Sim	Instância que será acompanhada.
`instanceToken`	`string`	Sim	Token da instância.
`events`	`VZapsEventType[]`	Não	Lista de eventos. Se omitido, usa eventos assinados na instância.
`reconnect`	`boolean`	Não	Reconectar automáticamente. Padrão: `true`.
`maxRetries`	`number`	Não	Máximo de tentativas.
`retryDelayMs`	`number`	Não	Delay entre tentativas.
`lastEventId`	`string`	Não	Cursor para retomada.
`signal`	`AbortSignal`	Não	Fechar assinatura quando abortar.

Registrar handlers

subscription.on('open', () => {
  console.log('Realtime conectado');
});

subscription.on('Message', (event) => {
  console.log(event.id);
  console.log(event.instance_id);
  console.dir(event.data, { depth: null });
});

subscription.on('All', (event) => {
  console.log('Evento recebido:', event.type);
});

subscription.on('error', (error) => {
  console.error('Erro realtime:', error);
});

Fechar assinatura

await subscription.close();

Retorno: Promise<void> apos fechar o WebSocket. Em processos Node.js:

process.on('SIGINT', async () => {
  await subscription.close();
  process.exit(0);
});

Envelope do evento

Cada evento recebido pelo SDK tem este formato:

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

Campos:

Campo	Descrição
`id`	Identificador do evento. Use para deduplicação.
`type`	Tipo do evento.
`instance_id`	Instância origem.
`created_at`	Data de criação do evento.
`data`	Payload do evento.
`data.media_url`	URL de mídia quando o evento recebido contém mídia e a plataforma disponibiliza o arquivo.

Entrega e ack

A entrega é at-least-once. Seu app deve tratar eventos de forma idempotente. Depois que o handler termina, o SDK envia ack automáticamente. Recomendações:

salve event.id se sua automação executa efeitos externos;
ignore eventos já processados;
use lastEventId ao reconectar se quiser reduzir lacunas;
mantenha handlers rápidos e mova trabalhos longos 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
Quer reprocessar entregas via logs	Webhook

​Eventos comuns

​Assinar realtime

​Registrar handlers

​Fechar assinatura

​Envelope do evento

​Entrega e ack

​Realtime ou webhook?