Conexão e autenticação

Além da API REST, o Zazz Chat expõe um gateway Socket.IO para eventos em tempo real — mensagens novas, mudanças de fila, capturas e transferências chegam ao seu cliente sem polling. É a mesma superfície que o aplicativo de atendimento oficial usa: se você está construindo a própria interface de atendimento, este é o canal.

Socket.IO não é WebSocket puro — use um cliente Socket.IO (protocolo Engine.IO v4). Em JavaScript: socket.io-client. Há clientes oficiais e da comunidade para Python, Java, Swift, Kotlin e outros.

Conexão

O gateway roda em um endereço separado da API REST — não use a mesma URL base. Solicite o endereço do gateway do seu ambiente ao suporte.

import { io } from "socket.io-client";

const socket = io(SOCKET_URL, {
  transports: ["websocket"],
  auth: { token: SEU_JWT }, // o mesmo token do POST /auth/login
});

socket.on("connect", () => console.log("conectado", socket.id));
socket.on("connect_error", (err) => console.error("falha na conexão:", err.message));

Autenticação

O handshake aceita o mesmo JWT retornado por POST /auth/login, por três vias — em ordem de prioridade:

Header Authorization: Bearer <jwt>
auth.token no handshake (recomendado para browsers, como no exemplo acima)
Cookie access_token

Uma conexão sem token é aceita pelo gateway, mas fica sem identidade — eventos endereçados ao seu usuário (fila pessoal, notificações, rascunhos) nunca chegam. Sempre conecte com o token.

Salas: como os eventos chegam até você

O gateway não envia tudo para todo mundo. Depois de conectar, o cliente entra em salas emitindo eventos de inscrição (veja Eventos do cliente) — e cada evento do servidor é entregue às salas relevantes. O fluxo típico de uma tela de atendimento:

Identifique a sessão

Emita user_logged_in com o userId do usuário logado — habilita notificações, fila pessoal e eventos de rascunho.

Entre nas salas das equipes

Emita user_join_team com os ids das equipes do atendente — habilita os eventos da fila de espera (conversa nova, transferência para a equipe).

Observe os chats visíveis

Emita user_start_watch_chats com os ids dos chats renderizados na lista — habilita atualizações desses itens.

Ao abrir uma conversa

Emita user_start_attendance com o chatId — habilita message.upsert/message.update daquela conversa.

Reconexão

O servidor mantém uma janela de recuperação de sessão de 2 minutos (salas e pacotes perdidos são restaurados em quedas curtas). Mesmo assim, sempre re-emita os eventos de inscrição (user_logged_in, user_join_team, user_start_watch_chats, user_start_attendance) no evento connect do cliente — a janela de recuperação vive em memória e não sobrevive a um restart do servidor.

socket.on("connect", () => {
  socket.emit("user_logged_in", userId);
  socket.emit("user_join_team", teamIds);
  socket.emit("user_start_watch_chats", visibleChatIds);
  if (openChatId) socket.emit("user_start_attendance", openChatId);
});

Após reconectar, recarregue o histórico da conversa aberta pela API REST — cobre mensagens que chegaram durante a queda, fora da janela de recuperação.

Versionamento

O vocabulário documentado nestas páginas faz parte do contrato v1:

Mudança quebra-compatibilidade (renomear evento, remover campo, mudar tipo) exige evento novo + descontinuação comunicada do antigo — nunca alteração in-place.
Mudança aditiva (campo novo opcional, evento novo) pode acontecer a qualquer momento — trate campos desconhecidos como ignoráveis.
Payloads novos carregam schemaVersion no envelope (mesmo padrão dos webhooks).

Fora do contrato v1 (sujeitos a mudança sem aviso): vocabulário de vídeo-chamada (call.*, whiteboard.*) e salas internas de administração do sistema.

API Reference

Webhooks

Socket (Tempo real)

Conexão e autenticação

Conexão

Autenticação

Salas: como os eventos chegam até você

Reconexão

Versionamento

​Conexão

​Autenticação

​Salas: como os eventos chegam até você

​Reconexão

​Versionamento

Conexão

Autenticação

Salas: como os eventos chegam até você

Reconexão

Versionamento