Definir Websocket

POST

api

events

websocket

:instance

Definir 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 ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: sim (upsert)

Descrição

Habilita / desabilita o canal WebSocket da instância e define o filtro de eventos. Diferente do webhook, existe uma única configuração por instância (não há label). Esse endpoint não abre conexão, apenas autoriza o upgrade posterior em GET /ws/:instance.

Exemplos

Habilitar tudo

Liga o WebSocket sem filtro: como events é omitido, o cliente recebe os 6 tipos de evento, e mediaBase64 permanece em 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)
}

Filtro estreito

Habilita o WebSocket recebendo somente message.exchange e message.status e ativa mediaBase64: true para que os frames com mídia já tragam o conteúdo binário codificado em base64.

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

Desativar o websocket

Desliga o WebSocket enviando enabled: false. A linha de configuração é preservada, events e mediaBase64 são zerados, e novas conexões em /ws/:instance passam a ser rejeitadas.

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

Resposta de sucesso

A resposta devolve o objeto websocket com a configuração efetivamente persistida (enabled, events, mediaBase64), espelha o body do request após o upsert. Quando enabled=false, events e mediaBase64 voltam zerados; conexões já abertas em /ws/:instance permanecem até serem fechadas naturalmente, mas novas conexões passam a ser rejeitadas com 400.

200 OK

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

Parâmetros de rota

string

obrigatório

Nome da instância.

Headers

string

obrigatório

TokenAccount ou TokenInstance.

string

obrigatório

application/json

Request body

boolean

obrigatório

Liga/desliga o WebSocket. Quando false, events e mediaBase64 são zerados antes do save.

string[]

padrão:"[]"

Filtro. Array vazio = recebe todos os 6 tipos. Valores devem estar em {message.exchange, message.status, call.update, group.flow, instance.state, label.update}.

boolean

padrão:"false"

Quando true, eventos message.exchange com mídia incluem media.base64 nos frames WS.

Notas

Não persiste eventos: WebSocket é efêmero. Se ninguém estiver conectado no momento do evento, ele é descartado (fast-path HasClients antes de qualquer trabalho de serialização).
Sem retry: se o socket cair durante o envio, a mensagem é perdida. Para entrega garantida, use webhook.
enabled=false não desconecta clientes já abertos: as conexões existentes em /ws/:instance permanecem até serem fechadas naturalmente; novas conexões falham com 400.
Sem limite documentado de conexões: cada instância pode ter N clientes simultâneos (broadcast). O hub mantém buffer de 256 mensagens por cliente, clientes lentos são desconectados automaticamente.
Configuração na criação: o mesmo bloco pode ser passado em POST /api/instance/new via websocketEnabled, websocketEvents, websocketMediaBase64.

Erros

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

Verificar config WebSocket

GET /api/events/getWebsocket/:instance

Conectar via WebSocket

GET /ws/:instance, protocolo, auth, reconexão.

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Definir Websocket

Descrição

Exemplos

Habilitar tudo

Filtro estreito

Desativar o websocket

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Notas

Erros

Próximo

Verificar config WebSocket

Conectar via WebSocket

​Descrição

​Exemplos

​Habilitar tudo

​Filtro estreito

​Desativar o websocket

​Resposta de sucesso

​Parâmetros de rota

​Headers

​Request body

​Notas

​Erros

​Próximo

Verificar config WebSocket

Conectar via WebSocket

Descrição

Exemplos

Habilitar tudo

Filtro estreito

Desativar o websocket

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Notas

Erros

Próximo