Conectar vía WebSocket

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.

​

Descripción

​

Ejemplos cURL (handshake)

​

Handshake (inspección)

curl -v --include \
  --header "Connection: Upgrade" \
  --header "Upgrade: websocket" \
  --header "Sec-WebSocket-Key: $(openssl rand -base64 16)" \
  --header "Sec-WebSocket-Version: 13" \
  --header "token: $Token_Instance" \
  "https://ryzeapi.cloud/ws/$Instance_Name"

​

wscat (interactivo)

# npm i -g wscat
wscat -c "wss://api.example.com/ws/$Instance_Name?token=$Token_Instance"

​

Ejemplos de cliente

const BASE = "wss://api.example.com";
const INSTANCE = "$Instance_Name";
const TOKEN = "a1b2c3d4-..."; // Account or Instance

let ws;
let reconnectDelay = 1000; // 1s, doubles up to 30s

function connect() {
  ws = new WebSocket(`${BASE}/ws/${INSTANCE}?token=${encodeURIComponent(TOKEN)}`);

  ws.addEventListener("open", () => {
    console.log("WS connected");
    reconnectDelay = 1000;
  });

  ws.addEventListener("message", (ev) => {
    try {
      const env = JSON.parse(ev.data);
      switch (env.event) {
        case "message.exchange":  handleMessage(env.data); break;
        case "instance.state":    handleState(env.data);   break;
        // ... other types
      }
    } catch (e) {
      console.error("Non-JSON frame:", ev.data);
    }
  });

  ws.addEventListener("close", (ev) => {
    console.warn(`Closed (code=${ev.code}). Reconnecting in ${reconnectDelay}ms...`);
    setTimeout(connect, reconnectDelay);
    reconnectDelay = Math.min(reconnectDelay * 2, 30000);
  });

  ws.addEventListener("error", (ev) => {
    console.error("WS error:", ev);
    // 'close' fires next
  });
}

connect();

import WebSocket from "ws";

const ws = new WebSocket("wss://api.example.com/ws/$Instance_Name", {
  headers: { token: process.env.Token_Instance }
});

ws.on("open",    () => console.log("connected"));
ws.on("message", (buf) => {
  const env = JSON.parse(buf.toString());
  console.log(env.event, env.data);
});
ws.on("close",   (code, reason) => console.warn("closed", code, reason?.toString()));
ws.on("error",   (e) => console.error(e));

import asyncio, json, os, websockets

async def consume():
    url = "wss://api.example.com/ws/$Instance_Name"
    headers = {"token": os.environ["Token_Instance"]}
    async with websockets.connect(url, extra_headers=headers) as ws:
        async for raw in ws:
            env = json.loads(raw)
            print(env["event"], env["data"])

asyncio.run(consume())

package main

import (
    "log"
    "net/http"
    "github.com/gorilla/websocket"
)

func main() {
    h := http.Header{}
    h.Set("token", "a1b2c3d4-...")
    c, _, err := websocket.DefaultDialer.Dial(
        "wss://api.example.com/ws/$Instance_Name", h)
    if err != nil { log.Fatal(err) }
    defer c.Close()

    for {
        _, msg, err := c.ReadMessage()
        if err != nil { log.Fatal(err) }
        log.Printf("%s", msg)
    }
}

​

Envoltorio de los frames recibidos

{
  "event": "message.exchange",
  "data": { /* specific payload */ },
  "instanceData": {
    "baseUrl": "https://api.example.com",
    "instance": "$Instance_Name",
    "token":    "<instance-token>"
  }
}

​

Parámetros de ruta

​

Cabeceras

​

Parámetros de consulta

​

Precondiciones

1. Existe una configuración en websocket_configs para la instancia (creada vía POST /api/events/websocket/:instance) con enabled=true.
2. Token válido, TokenAccount o TokenInstance de la instancia (misma matriz que REST).
3. Si proviene de un navegador, el Origin del request está en ALLOWED_WS_ORIGINS o es same-origin.

​

Autenticación

​

Validación de Origin (ALLOWED_WS_ORIGINS)

​

Heartbeat

​

Buffers y backpressure

​

Catálogo de eventos

​

Reconexión y resiliencia

​

Efectos colaterales

• Hub en memoria: el handler registra al cliente en WebSocketHub (map[instanceName]map[*WebSocketClient]bool). La conexión no se persiste. Un restart del proceso los descarta a todos.
• Goroutines: cada conexión genera 2 goroutines (WritePump y ReadPump) que viven hasta el close.
• Sin escritura en BD: el upgrade en sí no escribe nada. Los broadcasts subsiguientes pasan por el dispatcher de webhook (que toca la BD) en paralelo, el WS es solo un fanout adicional.
• Métricas Prometheus: contadores de conexiones activas por instancia (consulta /es/api/observability/overview).

​

Notas

​

Cuándo usar webhook vs WebSocket

​

Errores antes del upgrade

{
  "success": false,
  "error": {
    "message": "WebSocket is not enabled for this instance. Configure it first using POST /api/events/websocket/$Instance_Name"
  }
}

​

Errores después del upgrade

• Frame del cliente mayor a 4096 bytes.
• pongWait (60s) expiró sin respuesta al PING.
• Send buffer del cliente lleno (cliente lento), el hub lo desregistra.
• La instancia fue eliminada mientras el cliente estaba conectado.

​

Referencias