Set Websocket

POST

api

events

websocket

:instance

Set 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 or TokenInstance • Rate limit: Global (100/min) • Idempotent: yes (upsert)

Description

Enables / disables the instance’s WebSocket channel and sets the event filter. Unlike the webhook, there is a single configuration per instance (no label). This endpoint does not open a connection, it only authorizes the later upgrade at GET /ws/:instance.

Examples

Enable everything

Turns on the WebSocket without any filter: since events is omitted, the client receives all 6 event types, and mediaBase64 stays 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)
}

Narrow filter

Enables the WebSocket receiving only message.exchange and message.status and turns on mediaBase64: true so frames with media already include the binary content base64-encoded.

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

Disable the websocket

Turns off the WebSocket by sending enabled: false. The configuration row is preserved, events and mediaBase64 are cleared, and new connections to /ws/:instance start being rejected.

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

Success response

The response returns the websocket object with the configuration actually persisted (enabled, events, mediaBase64), mirrors the request body after the upsert. When enabled=false, events and mediaBase64 come back cleared; connections already open at /ws/:instance remain until closed naturally, but new connections start being rejected with 400.

200 OK

{
  "success": true,
  "message": "WebSocket configured successfully",
  "websocket": {
    "enabled":     true,
    "events":      ["message.exchange", "instance.state"],
    "mediaBase64": false
  }
}

Path parameters

string

required

Instance name.

Headers

string

required

TokenAccount or TokenInstance.

string

required

application/json

Request body

boolean

required

Turns the WebSocket on/off. When false, events and mediaBase64 are cleared before saving.

string[]

default:"[]"

Filter. Empty array = receive all 6 types. Values must be in {message.exchange, message.status, call.update, group.flow, instance.state, label.update}.

boolean

default:"false"

When true, message.exchange events with media include media.base64 in the WS frames.

Notes

Does not persist events: WebSocket is ephemeral. If no one is connected at the moment of the event, it’s discarded (fast-path HasClients before any serialization work).
No retry: if the socket drops during send, the message is lost. For guaranteed delivery, use webhook.
enabled=false does not disconnect already-open clients: existing connections at /ws/:instance remain until closed naturally; new connections fail with 400.
No documented connection limit: each instance can have N simultaneous clients (broadcast). The hub keeps a 256-message buffer per client; slow clients are disconnected automatically.
Configuration at creation time: the same block can be passed to POST /api/instance/new via websocketEnabled, websocketEvents, websocketMediaBase64.

Errors

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`

Envelope:

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

Check WebSocket config

GET /api/events/getWebsocket/:instance

Connect via WebSocket

GET /ws/:instance, protocol, auth, reconnection.

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Description

Examples

Enable everything

Narrow filter

Disable the websocket

Success response

Path parameters

Headers

Request body

Notes

Errors

Next

Check WebSocket config

Connect via WebSocket

​Description

​Examples

​Enable everything

​Narrow filter

​Disable the websocket

​Success response

​Path parameters

​Headers

​Request body

​Notes

​Errors

​Next

Check WebSocket config

Connect via WebSocket

Description

Examples

Enable everything

Narrow filter

Disable the websocket

Success response

Path parameters

Headers

Request body

Notes

Errors

Next