Configurar Websocket

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
}
'

const options = {
  method: 'POST',
  headers: {token: '<token>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({enabled: true, events: ['<string>'], mediaBase64: true})
};

fetch('https://api.example.com/api/events/websocket/:instance', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/api/events/websocket/:instance"

payload = {
    "enabled": True,
    "events": ["<string>"],
    "mediaBase64": True
}
headers = {
    "token": "<token>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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}'

await fetch(`https://ryzeapi.cloud/api/events/websocket/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ enabled: true })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/events/websocket/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={"enabled": True}
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{"enabled": true}`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/events/websocket/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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
  }'

await fetch(`https://ryzeapi.cloud/api/events/websocket/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    enabled:     true,
    events:      ["message.exchange", "message.status"],
    mediaBase64: true
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/events/websocket/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "enabled":     True,
        "events":      ["message.exchange", "message.status"],
        "mediaBase64": True
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "enabled":     true,
        "events":      ["message.exchange", "message.status"],
        "mediaBase64": true
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/events/websocket/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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}'

await fetch(`https://ryzeapi.cloud/api/events/websocket/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ enabled: false })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/events/websocket/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={"enabled": False}
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{"enabled": false}`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/events/websocket/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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

string

requerido

Nombre de la instancia.

Cabeceras

string

requerido

TokenAccount o TokenInstance.

string

requerido

application/json

Cuerpo de la solicitud

boolean

requerido

Activa/desactiva el WebSocket. Cuando es false, events y mediaBase64 se limpian antes de guardar.

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

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

HTTP	`error.message`
400	`Invalid request body`
401	`Invalid token`
404	`Instance not found`
429	`Rate limit exceeded. Try again later.`
500	`Failed to get instance`

Envoltorio:

{
  "success": false,
  "error": { "message": "Invalid request body" }
}

Consultar configuración del WebSocket

GET /api/events/getWebsocket/:instance

Conectar vía WebSocket

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

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Configurar Websocket

Descripción

Ejemplos

Habilitar todo

Filtro estrecho

Deshabilitar el websocket

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas

Errores

Siguiente

Consultar configuración del WebSocket

Conectar vía WebSocket

​Descripción

​Ejemplos

​Habilitar todo

​Filtro estrecho

​Deshabilitar el websocket

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Cuerpo de la solicitud

​Notas

​Errores

​Siguiente

Consultar configuración del WebSocket

Conectar vía WebSocket

Descripción

Ejemplos

Habilitar todo

Filtro estrecho

Deshabilitar el websocket

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas

Errores

Siguiente