Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt

Use this file to discover all available pages before exploring further.

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

MétodoPathFunção
POST/api/events/webhook/:instanceConfigurar webhook (até 3 habilitados)
GET/api/events/getWebhook/:instanceListar webhooks ou obter um por ?label=
POST/api/events/websocket/:instanceConfigurar WebSocket ({"enabled": false} desabilita)
GET/api/events/getWebsocket/:instanceLer config atual do WebSocket
GET/ws/:instanceConectar via WebSocket (upgrade)
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: 
{
  "event": "message.exchange",
  "data": { /* payload específico do evento */ },
  "instanceData": {
    "baseUrl": "https://api.example.com",
    "instance": "$Instance_Name",
    "token": "<instance-token>"
  }
}
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

AspectoWebhookWebSocket
ProtocoloHTTP POSTWS (upgrade TCP)
EntregaAsync, persistida em filaReal-time, em memória
Retry/DLQBackoff exponencial 1s→1h, até 5 tentativas + DLQSem retry, eventos perdidos se cliente offline
Filtro de eventosevents[] por configevents[] por config
Mídia em base64mediaBase64 opcionalmediaBase64 opcional
AutenticaçãoHeader Authorization configurávelToken no upgrade (header ou ?token=)
HeartbeatN/APING/PONG ~54s/60s
LimiteAté 3 webhooks habilitados por instância1 config por instância (broadcast a N clientes conectados)
BackpressureFila cresce no DBBuffer de 256 msgs por cliente; lentos são dropados
Sobrevive a queda do consumer?SimNão

​
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.