Saltar al contenido 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.

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

MétodoRutaFunción
POST/api/events/webhook/:instanceConfigurar webhook (hasta 3 habilitados)
GET/api/events/getWebhook/:instanceListar webhooks u obtener uno por ?label=
POST/api/events/websocket/:instanceConfigurar WebSocket ({"enabled": false} desactiva)
GET/api/events/getWebsocket/:instanceLeer la configuración actual del WebSocket
GET/ws/:instanceConectar vía WebSocket (upgrade)
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: 
{
  "event": "message.exchange",
  "data": { /* event-specific payload */ },
  "instanceData": {
    "baseUrl": "https://api.example.com",
    "instance": "$Instance_Name",
    "token": "<instance-token>"
  }
}
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

AspectoWebhookWebSocket
ProtocoloHTTP POSTWS (TCP upgrade)
EntregaAsíncrona, persistida en colaTiempo real, en memoria
Retry/DLQBackoff exponencial 1s→1h, hasta 5 intentos + DLQSin retry, los eventos se pierden si el cliente está offline
Filtro de eventosevents[] por configuraciónevents[] por configuración
Media en base64mediaBase64 opcionalmediaBase64 opcional
AutenticaciónCabecera Authorization configurableToken en el upgrade (cabecera o ?token=)
HeartbeatN/APING/PONG ~54s/60s
LímiteHasta 3 webhooks habilitados por instancia1 configuración por instancia (broadcast a N clientes conectados)
BackpressureLa cola crece en la BDBuffer de 256 mensajes por cliente; los lentos se descartan
¿Sobrevive a crash del consumidor?SíNo

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