Skip to main content

​
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

TipoQuandoPayload
authLogo após a conexão abrir{ access_token: string }
pingA cada 30s (heartbeat)—

​
Recebidas do servidor

TipoQuandoPayload
pongResposta ao ping—
state_changedEstado 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:
  1. Reconectar com backoff exponencial ao perder conexão.
  2. Re-autenticar após a reconexao.
  3. 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.