Connect via WebSocket

​

Description

​

cURL examples (handshake)

​

Handshake (inspection)

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

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

​

Client examples

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

​

Envelope of received frames

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

​

Path parameters

​

Headers

​

Query parameters

​

Preconditions

1. There is a config in websocket_configs for the instance (created via POST /api/events/websocket/:instance) with enabled=true.
2. Valid token, TokenAccount or TokenInstance of the instance (same matrix as REST).
3. If coming from a browser, the request Origin is in ALLOWED_WS_ORIGINS or is same-origin.

​

Authentication

​

Origin validation (ALLOWED_WS_ORIGINS)

​

Heartbeat

​

Buffers and backpressure

​

Event catalog

​

Reconnection and resilience

​

Side effects

• In-memory hub: the handler registers the client in WebSocketHub (map[instanceName]map[*WebSocketClient]bool). The connection is not persisted. A process restart drops them all.
• Goroutines: each connection spawns 2 goroutines (WritePump and ReadPump) that live until close.
• No DB write: the upgrade itself writes nothing. Subsequent broadcasts go through the webhook dispatcher (which touches the DB) in parallel, WS is just an additional fanout.
• Prometheus metrics: counters of active connections per instance (see /en/api/observability/overview).

​

Notes

​

When to use webhook vs WebSocket

​

Errors before the upgrade

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

​

Errors after the upgrade

• Client frame larger than 4096 bytes.
• pongWait (60s) expired without a reply to the PING.
• Client send buffer full (slow client), the hub unregisters it.
• Instance was deleted while the client was connected.

​

References