Saltar al contenido principal
POST
/
api
/
events
/
websocket
/
:instance
Configurar Websocket
curl --request POST \
  --url https://api.example.com/api/events/websocket/:instance \
  --header 'Content-Type: <content-type>' \
  --header 'token: <token>' \
  --data '
{
  "enabled": true,
  "events": [
    "<string>"
  ],
  "mediaBase64": true
}
'
Auth: TokenAccount o TokenInstance • Rate limit: Global (100/min) • Idempotente: sí (upsert)

​
Descripción

Habilita / deshabilita el canal WebSocket de la instancia y define el filtro de eventos. A diferencia del webhook, hay una única configuración por instancia (sin label). Este endpoint no abre una conexión, solo autoriza el upgrade posterior en GET /ws/:instance.

​
Ejemplos

​
Habilitar todo

Activa el WebSocket sin ningún filtro: como events se omite, el cliente recibe los 6 tipos de eventos, y mediaBase64 permanece como false. 
curl -X POST "https://ryzeapi.cloud/api/events/websocket/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

​
Filtro estrecho

Habilita el WebSocket recibiendo solo message.exchange y message.status y activa mediaBase64: true para que los frames con media ya incluyan el contenido binario codificado en base64. 
curl -X POST "https://ryzeapi.cloud/api/events/websocket/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled":     true,
    "events":      ["message.exchange", "message.status"],
    "mediaBase64": true
  }'

​
Deshabilitar el websocket

Desactiva el WebSocket enviando enabled: false. La fila de configuración se preserva, events y mediaBase64 se limpian, y las nuevas conexiones a /ws/:instance empiezan a ser rechazadas. 
curl -X POST "https://ryzeapi.cloud/api/events/websocket/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

​
Respuesta exitosa

La respuesta retorna el objeto websocket con la configuración efectivamente persistida (enabled, events, mediaBase64), refleja el body de la solicitud después del upsert. Cuando enabled=false, events y mediaBase64 regresan limpios; las conexiones ya abiertas en /ws/:instance se mantienen hasta cerrarse naturalmente, pero las nuevas conexiones empiezan a ser rechazadas con 400.
200 OK
{
  "success": true,
  "message": "WebSocket configured successfully",
  "websocket": {
    "enabled":     true,
    "events":      ["message.exchange", "instance.state"],
    "mediaBase64": false
  }
}

​
Parámetros de ruta

​
instance
string
requerido
Nombre de la instancia.

​
Cabeceras

​
token
string
requerido
TokenAccount o TokenInstance.
​
Content-Type
string
requerido
application/json

​
Cuerpo de la solicitud

​
enabled
boolean
requerido
Activa/desactiva el WebSocket. Cuando es false, events y mediaBase64 se limpian antes de guardar.
​
events
string[]
predeterminado:"[]"
Filtro. Array vacío = recibir los 6 tipos. Los valores deben estar en {message.exchange, message.status, call.update, group.flow, instance.state, label.update}.
​
mediaBase64
boolean
predeterminado:"false"
Cuando es true, los eventos message.exchange con media incluyen media.base64 en los frames del WS.

​
Notas

  • No persiste eventos: el WebSocket es efímero. Si nadie está conectado en el momento del evento, se descarta (fast-path HasClients antes de cualquier trabajo de serialización).
  • Sin retry: si el socket cae durante el envío, el mensaje se pierde. Para entrega garantizada, usa webhook.
  • enabled=false no desconecta clientes ya abiertos: las conexiones existentes en /ws/:instance se mantienen hasta cerrarse naturalmente; las nuevas conexiones fallan con 400.
  • No hay límite de conexión documentado: cada instancia puede tener N clientes simultáneos (broadcast). El hub mantiene un buffer de 256 mensajes por cliente; los clientes lentos son desconectados automáticamente.
  • Configuración al momento de la creación: el mismo bloque puede pasarse a POST /api/instance/new vía websocketEnabled, websocketEvents, websocketMediaBase64.

​
Errores

HTTPerror.message
400Invalid request body
401Invalid token
404Instance not found
429Rate limit exceeded. Try again later.
500Failed to get instance
Envoltorio: 
{
  "success": false,
  "error": { "message": "Invalid request body" }
}

​
Siguiente

Consultar configuración del WebSocket

GET /api/events/getWebsocket/:instance

Conectar vía WebSocket

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