Conectar via 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.

​

Descrição

​

Exemplos cURL (handshake)

​

Handshake (inspeção)

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 (interativo)

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

​

Exemplos de cliente

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

let ws;
let reconnectDelay = 1000; // 1s, dobra até 30s

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

  ws.addEventListener("open", () => {
    console.log("WS conectado");
    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;
        // ... demais tipos
      }
    } catch (e) {
      console.error("Frame não-JSON:", ev.data);
    }
  });

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

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

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("conectado"));
ws.on("message", (buf) => {
  const env = JSON.parse(buf.toString());
  console.log(env.event, env.data);
});
ws.on("close",   (code, reason) => console.warn("fechou", 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)
    }
}

​

Envelope dos frames recebidos

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

​

Parâmetros de rota

​

Headers

​

Query parameters

​

Pré-condições

1. Existe uma config em websocket_configs para a instância (criada via POST /api/events/websocket/:instance) com enabled=true.
2. Token válido, TokenAccount ou TokenInstance da instância (mesma matriz do REST).
3. Se vier de browser, o Origin do request está em ALLOWED_WS_ORIGINS ou é same-origin.

​

Autenticação

​

Validação de Origin (ALLOWED_WS_ORIGINS)

​

Heartbeat

​

Buffers e backpressure

​

Catálogo de eventos

​

Reconexão e resiliência

​

Efeitos colaterais

• Hub em memória: o handler registra o cliente em WebSocketHub (map[instanceName]map[*WebSocketClient]bool). A conexão não é persistida. Reinício do processo derruba todos.
• Goroutines: cada conexão lança 2 goroutines (WritePump e ReadPump) que vivem até o close.
• Sem DB write: o upgrade em si não escreve nada. Broadcasts subsequentes passam pelo dispatcher de webhook (que toca DB) em paralelo, WS é apenas fanout adicional.
• Métricas Prometheus: contadores de conexões ativas por instância (ver /api/observability/overview).

​

Notas

​

Quando usar webhook vs WebSocket

​

Erros antes do upgrade

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

​

Erros após o upgrade

• Frame do cliente maior que 4096 bytes.
• pongWait (60s) expirou sem resposta ao PING.
• Buffer de envio do cliente cheio (cliente lento), hub faz unregister.
• Instância foi deletada enquanto o cliente estava conectado.

​

Referências