Skip to main content
O módulo Eventos é como você recebe o que acontece na sua instância em tempo real. A RyzeAPI emite eventos por dois canais independentes que compartilham o mesmo envelope e o mesmo catálogo:

Webhook (HTTP push)

A RyzeAPI faz POST na sua URL toda vez que um evento ocorre. Persistido em fila com retry/backoff e DLQ. Ideal para servidores, CRMs, automações.

WebSocket (push em tempo real)

O cliente abre uma conexão e recebe os eventos na hora. Sem persistência, ideal para dashboards, painéis ao vivo, telas de atendimento.
Nada impede usar os dois ao mesmo tempo: webhook cuida da entrega persistente para o backend, WebSocket faz a UI saltar quando o evento chega.

​
Endpoints do módulo

A configuração de webhook e WebSocket também pode ser feita na criação da instância, basta enviar webhookEnabled, webhookURL, websocketEnabled, etc. no body de POST /api/instance/new.

​
Envelope compartilhado

Tanto webhook quanto WebSocket entregam o mesmo objeto:
instanceData.token é o token da própria instância, útil quando seu consumidor centraliza várias instâncias e precisa identificar a origem.

​
Os 6 tipos de evento

message.exchange

Mensagens enviadas/recebidas (texto, mídia, sticker, doc, enquete, contato, localização, botão/lista, edits e revogações).

message.status

Recibos de entrega: delivered, read, played, read_self, played_self etc.

call.update

Chamadas: offer, accepted, rejected, terminated, notification, latency.

group.flow

Mudanças em grupos: joined/left/promoted/demoted + metadata (name, topic, announce, link, etc.).

instance.state

Mudanças de conexão da instância: connected, qr_ready, temp_banned, logged_out, pair_success…

label.update

Etiquetas WhatsApp Business: edição, associação a chats e mensagens.

Catálogo completo de eventos

Schemas de payload, enums e exemplos de cada um dos 6 tipos.

​
Webhook x WebSocket

​
Múltiplos webhooks por instância

Cada instância aceita até 3 webhooks habilitados simultâneos, você os identifica por um label. Permite, por exemplo:
  • default para o sistema principal de produção
  • analytics-pipeline para um sink de eventos
  • staging-mirror para validar mudanças em paralelo
Cada label tem URL, eventos filtrados, authorization e mediaBase64 próprios. Ver configurar webhook.

​
Boas práticas

Responda 2xx em menos de 5s no endpoint webhook, caso contrário, a entrega entra em retry com backoff exponencial.
Valide a origem com o header Authorization configurado, não há HMAC automático, o consumidor é responsável.
mediaBase64: false se você precisa só da URL/s3Url, economiza banda e DB.
Reconecte com backoff no WebSocket, não há resumo de sessão; eventos perdidos não voltam.
Filtre events[] quando souber exatamente o que vai consumir, reduz tráfego e processamento.

​
Próximos passos

Configurar webhook

POST /api/events/webhook/:instance, cria/atualiza por label.

Listar webhooks

GET /api/events/getWebhook/:instance, todos ou por ?label=.

Configurar WebSocket

POST /api/events/websocket/:instance, enabled, events, mediaBase64.

Verificar config do WebSocket

GET /api/events/getWebsocket/:instance.

Catálogo de eventos

Schemas e exemplos dos 6 tipos.

Conectar via WebSocket

GET /ws/:instance, protocolo, auth, reconexão.