Pular para o conteúdo principal
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
}
'
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}'

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

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

​
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

​
instance
string
obrigatório
Nome da instância.

​
Headers

​
token
string
obrigatório
TokenAccount ou TokenInstance.
​
Content-Type
string
obrigatório
application/json

​
Request body

​
enabled
boolean
obrigatório
Liga/desliga o WebSocket. Quando false, events e mediaBase64 são zerados antes do save.
​
events
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}.
​
mediaBase64
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

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

​
Próximo

Verificar config WebSocket

GET /api/events/getWebsocket/:instance

Conectar via WebSocket

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