Skip to main content
El módulo de Eventos es la forma de recibir lo que ocurre en tu instancia en tiempo real. RyzeAPI emite eventos a través de dos canales independientes que comparten el mismo envoltorio y el mismo catálogo:

Webhook (HTTP push)

RyzeAPI hace POST a tu URL cada vez que ocurre un evento. Persistido en una cola con retry/backoff y DLQ. Ideal para servidores, CRMs, automatizaciones.

WebSocket (push en tiempo real)

El cliente abre una conexión y recibe los eventos al instante. Sin persistencia, ideal para dashboards, paneles en vivo, pantallas de soporte.
Nada impide usar ambos a la vez: el webhook se encarga de la entrega persistente al backend mientras el WebSocket hace que la UI reaccione en el momento en que llega el evento.

​
Endpoints del módulo

La configuración de webhook y WebSocket también puede hacerse en la creación de la instancia, basta con enviar webhookEnabled, webhookURL, websocketEnabled, etc. en el body de POST /api/instance/new.

​
Envoltorio compartido

Tanto el webhook como el WebSocket entregan el mismo objeto:
instanceData.token es el propio token de la instancia, útil cuando tu consumidor centraliza varias instancias y necesita identificar el origen.

​
Los 6 tipos de eventos

message.exchange

Mensajes enviados/recibidos (texto, media, sticker, doc, encuesta, contacto, ubicación, botón/lista, ediciones y revocaciones).

message.status

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

call.update

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

group.flow

Cambios de grupo: joined/left/promoted/demoted + metadatos (name, topic, announce, link, etc.).

instance.state

Cambios de conexión de la instancia: connected, qr_ready, temp_banned, logged_out, pair_success…

label.update

Etiquetas de WhatsApp Business: ediciones, asociación con chats y mensajes.

Catálogo completo de eventos

Esquemas de payload, enums y ejemplos para cada uno de los 6 tipos.

​
Webhook vs WebSocket

​
Múltiples webhooks por instancia

Cada instancia acepta hasta 3 webhooks habilitados simultáneamente, identificados por un label. Esto te permite, por ejemplo:
  • default para el sistema principal de producción
  • analytics-pipeline para un sink de eventos
  • staging-mirror para validar cambios en paralelo
Cada label tiene su propia URL, filtro de eventos, authorization y mediaBase64. Ver configurar webhook.

​
Buenas prácticas

Responde 2xx en menos de 5s en el endpoint del webhook, de lo contrario la entrega entra en retry con backoff exponencial.
Valida el origen con la cabecera Authorization configurada, no hay HMAC automático, el consumidor es responsable.
mediaBase64: false si solo necesitas la URL/s3Url, ahorra ancho de banda y espacio en BD.
Reconecta con backoff en el WebSocket, no hay reanudación de sesión; los eventos perdidos no regresan.
Filtra events[] cuando sepas exactamente lo que vas a consumir, reduciendo tráfico y procesamiento.

​
Próximos pasos

Configurar webhook

POST /api/events/webhook/:instance, crea/actualiza por label.

Listar webhooks

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

Configurar WebSocket

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

Consultar configuración del WebSocket

GET /api/events/getWebsocket/:instance.

Catálogo de eventos

Esquemas y ejemplos de los 6 tipos.

Conectar vía WebSocket

GET /ws/:instance, protocolo, autenticación, reconexión.