Skip to main content
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
}
'
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}'

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

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

​
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

​
instance
string
required
Instance name.

​
Headers

​
token
string
required
TokenAccount or TokenInstance.
​
Content-Type
string
required
application/json

​
Request body

​
enabled
boolean
required
Turns the WebSocket on/off. When false, events and mediaBase64 are cleared before saving.
​
events
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}.
​
mediaBase64
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

HTTPerror.message
400Invalid request body
401Invalid token
404Instance not found
429Rate limit exceeded. Try again later.
500Failed to get instance
Envelope: 
{
  "success": false,
  "error": { "message": "Invalid request body" }
}

​
Next

Check WebSocket config

GET /api/events/getWebsocket/:instance

Connect via WebSocket

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