Docs
Páginas desta seção

Guias

Tempo real (WebSockets)

As conexões WebSocket que mantêm conversas, chamadas e fluxos atualizados, como abri-las com um ticket e como retomar os eventos do workspace.

Além das rotas HTTP, a API mantém conexões WebSocket para o que muda o tempo todo: a caixa de entrada e as conversas, os eventos do workspace, as chamadas de voz e as ferramentas de edição de fluxos. A conexão fica aberta, e o servidor envia cada novidade assim que ela acontece.

Conexões

Todas partem do endereço de WebSocket da API, wss://api.vozkoia.com:

EndereçoPara que servePermissão no workspace
/ws/conversationsCaixa de entrada e conversas em tempo real: novas mensagens, leituras, digitação, mudanças de etapa, etiquetas, responsável e status. Também é por ela que o atendente envia mensagens. Com since, traz os eventos do workspace.conversations:read (e events:read para os eventos)
/ws/call-sessionSessão de chamadas de voz do atendente. Só para pessoas.call_session:use
/ws/workflows/{id}/simulateSimulador de um fluxo. Só para pessoas.workflows:update

Autenticação com ticket

O token nunca vai na URL. Para abrir uma conexão, peça antes um ticket com o mesmo token de login das rotas HTTP, ou com a chave de API de uma integração:

http
POST /v1/realtime/tickets
Authorization: Bearer SEU_TOKEN_OU_CHAVE
X-Workspace-ID: SEU_WORKSPACE_ID
X-Department-ID: SEU_DEPARTAMENTO_ID

X-Department-ID é opcional. A resposta é 201:

json
{ "ticket": "rtk_Q2hhdmUgZGUgZXhlbXBsbyBkZSAzMiBieXRlcyBhcXVp", "expiresAt": "2026-11-04T15:00:30Z" }

Abra a conexão com o ticket no parâmetro ticket:

text
wss://api.vozkoia.com/ws/conversations?ticket=SEU_TICKET
  • O ticket vale 30 segundos e abre uma única conexão. A cada conexão e a cada reconexão, peça um novo.
  • O ticket fica preso a quem o pediu, ao workspace e ao departamento do pedido. A conexão usa esse workspace e esse departamento, então não é preciso repeti-los na URL. Um workspaceId, workspace_id ou departmentId diferente na URL é recusado.
  • Ao conectar, o servidor confere de novo a sessão: um token revogado depois de pedir o ticket não abre a conexão.
  • Clientes que não são navegadores podem, em vez do ticket, enviar o cabeçalho Authorization: Bearer SEU_ACCESS_TOKEN ao abrir a conexão, com o workspace em X-Workspace-ID.
  • O token no parâmetro token da URL e o cookie de login não abrem WebSockets.

Antes de abrir o WebSocket, as recusas voltam como HTTP comum:

codeQuando
realtime_ticket_invalidO ticket não existe, venceu ou já foi usado. Peça outro.
realtime_ticket_unavailableNão foi possível emitir ou conferir o ticket agora. Tente de novo em instantes.
realtime_ticket_not_acceptedO ticket é de uma integração e a conexão é só para pessoas.
workspace_mismatch, department_mismatchA URL ou os cabeçalhos indicam outro workspace ou outro departamento que o do ticket.
auth_token_missingA conexão chegou sem ticket e sem o cabeçalho Authorization.

Eventos do workspace por seq

Com o parâmetro since, /ws/conversations também entrega o registro de eventos do workspace, o mesmo de GET /v1/events e com as mesmas regras de quem vê cada evento:

text
wss://api.vozkoia.com/ws/conversations?ticket=SEU_TICKET&since=184467
  1. Primeiro chegam, em ordem de seq, os eventos guardados depois de since.
  2. Em seguida, cada evento novo assim que é registrado.

Cada evento chega no quadro workspace_event, com o mesmo formato de GET /v1/events:

json
{
  "type": "workspace_event",
  "payload": {
    "id": "evt_184468",
    "type": "message.received",
    "seq": 184468,
    "createdAt": "2026-11-04T15:00:00Z",
    "workspaceId": "SEU_WORKSPACE_ID",
    "departmentId": null,
    "data": { "conversationId": "...", "messageId": "..." }
  }
}

Guarde o seq do último evento processado e use-o em since ao reconectar: nada se perde entre uma conexão e outra. A sequência pode pular números, porque os eventos que você não pode ler não chegam.

Os eventos ficam 7 dias. Um since mais antigo que isso recebe primeiro o quadro resync_required:

json
{ "type": "resync_required", "payload": { "code": "resync_required", "message": "...", "oldestSeq": 170001 } }

Busque pela API o estado atual do que você acompanha; os eventos seguem a partir do oldestSeq.

since precisa ser um número inteiro a partir de 0, e os eventos exigem events:read. Sem isso a conexão é recusada antes de abrir, com events_since_invalid ou read_permission_required.

Integrações

Uma integração pede o ticket com a chave de API dela e abre só /ws/conversations. Essa conexão traz apenas os quadros workspace_event e resync_required: sem since, os eventos começam do início da janela. A integração não aparece entre os usuários conectados, e as mensagens que ela envia pela conexão são ignoradas. Ela precisa de conversations:read e events:read. Quem não mantém uma conexão aberta lê os mesmos eventos em GET /v1/events.

Mensagens

As mensagens nos dois sentidos são objetos JSON com o tipo do evento em type e os dados em payload:

json
{
  "type": "subscribe",
  "payload": {}
}

Os tipos de evento de cada conexão, e o formato do payload de cada um, estão no grupo WebSockets da Referência da API.

Manter a conexão

  • Em /ws/conversations, o servidor envia um ping a cada 54 segundos. Navegadores e a maioria das bibliotecas respondem sozinhos; sem resposta em 60 segundos, a conexão é encerrada.
  • Em /ws/conversations, cada mensagem enviada pelo cliente pode ter até 512 KiB.
  • Conexões caem: reconecte com espera crescente, com um ticket novo a cada tentativa. Ao reconectar, use since para recuperar os eventos do intervalo, ou recarregue pela API HTTP o que pode ter mudado.