WebSocket em tempo real

Para receber atualizações ao vivo (sem polling) das mudanças de estado das entidades, conecte-se ao endpoint WebSocket do Portal.

Endpoint

wss://portal.unicontrol.me/v1/websocket

Autenticação

O WebSocket usa um fluxo de autenticação em duas etapas: primeiro você conecta, depois envia uma mensagem auth com o token.

O WebSocket atual aceita OAuth access token (JWT do Logto). PAT (pat_...) não funciona neste endpoint. Para integrações via WebSocket use o fluxo OAuth oficial — entre em contato com o suporte para receber as credenciais OAuth client.

Fluxo básico (JavaScript)

const ws = new WebSocket("wss://portal.unicontrol.me/v1/websocket");

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "auth",
    access_token: SEU_ACCESS_TOKEN_OAUTH
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log("recebido:", msg);
};

// Heartbeat — envie um ping a cada 30s para manter a conexao viva
setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ type: "ping" }));
  }
}, 30_000);

Tipos de mensagem

Enviadas pelo cliente

Tipo	Quando	Payload
`auth`	Logo após a conexão abrir	`{ access_token: string }`
`ping`	A cada 30s (heartbeat)	—

Recebidas do servidor

Tipo	Quando	Payload
`pong`	Resposta ao ping	—
`state_changed`	Estado de qualquer entidade do usuário mudou	`{ entity_id, old_state, new_state }`

Quando NÃO usar WebSocket

Você so precisa do estado atual uma vez — use /v1/states/{entity_id}.
Você quer histórico — use /v1/history.
Você roda em ambiente sem WebSocket persistente (lambda, edge function) — prefira polling ou webhooks de saida.

Reconexao e robustez

WebSockets caem. Sua integração deve:

Reconectar com backoff exponencial ao perder conexão.
Re-autenticar após a reconexao.
Re-sincronizar estado: depois de reconectar, busque /v1/entities/states para não perder mudanças que ocorreram durante o gap.

function connect(retry = 0) {
  const ws = new WebSocket("wss://portal.unicontrol.me/v1/websocket");

  ws.onopen = () => {
    ws.send(JSON.stringify({ type: "auth", access_token: TOKEN }));
    syncStates(); // GET /v1/entities/states
    retry = 0;
  };

  ws.onclose = () => {
    const delay = Math.min(30_000, 1000 * 2 ** retry);
    setTimeout(() => connect(retry + 1), delay);
  };
}

Para uso massivo (sistemas multi-tenant, dashboards de muitos clientes), considere uma camada própria de cache que assina o WebSocket uma vez por conta e revende as atualizações aos seus clientes — em vez de cada cliente abrir sua própria conexão.

Webhooks Limites e Erros

Começando

Painel de Controle

Dispositivos

Automações

Scripts

Assistente IA

Assistentes de Voz

Organização

Planos e Cobrança

Tags

Aplicativo Móvel

Registro de Atividade

Perfil e Segurança

Manual do Integrador

Legal

WebSocket em tempo real

WebSocket em tempo real

Endpoint

Autenticação

Fluxo básico (JavaScript)

Tipos de mensagem

Enviadas pelo cliente

Recebidas do servidor

Quando NÃO usar WebSocket

Reconexao e robustez

​WebSocket em tempo real

​Endpoint

​Autenticação

​Fluxo básico (JavaScript)

​Tipos de mensagem

​Enviadas pelo cliente

​Recebidas do servidor

​Quando NÃO usar WebSocket

​Reconexao e robustez

WebSocket em tempo real

Endpoint

Autenticação

Fluxo básico (JavaScript)

Tipos de mensagem

Enviadas pelo cliente

Recebidas do servidor

Quando NÃO usar WebSocket

Reconexao e robustez