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ço | Para que serve | Permissão no workspace |
|---|---|---|
/ws/conversations | Caixa 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-session | Sessão de chamadas de voz do atendente. Só para pessoas. | call_session:use |
/ws/workflows/{id}/simulate | Simulador 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:
POST /v1/realtime/tickets
Authorization: Bearer SEU_TOKEN_OU_CHAVE
X-Workspace-ID: SEU_WORKSPACE_ID
X-Department-ID: SEU_DEPARTAMENTO_IDX-Department-ID é opcional. A resposta é 201:
{ "ticket": "rtk_Q2hhdmUgZGUgZXhlbXBsbyBkZSAzMiBieXRlcyBhcXVp", "expiresAt": "2026-11-04T15:00:30Z" }Abra a conexão com o ticket no parâmetro ticket:
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_idoudepartmentIddiferente 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_TOKENao abrir a conexão, com o workspace emX-Workspace-ID. - O token no parâmetro
tokenda URL e o cookie de login não abrem WebSockets.
Antes de abrir o WebSocket, as recusas voltam como HTTP comum:
| code | Quando |
|---|---|
realtime_ticket_invalid | O ticket não existe, venceu ou já foi usado. Peça outro. |
realtime_ticket_unavailable | Não foi possível emitir ou conferir o ticket agora. Tente de novo em instantes. |
realtime_ticket_not_accepted | O ticket é de uma integração e a conexão é só para pessoas. |
workspace_mismatch, department_mismatch | A URL ou os cabeçalhos indicam outro workspace ou outro departamento que o do ticket. |
auth_token_missing | A 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:
wss://api.vozkoia.com/ws/conversations?ticket=SEU_TICKET&since=184467- Primeiro chegam, em ordem de
seq, os eventos guardados depois desince. - Em seguida, cada evento novo assim que é registrado.
Cada evento chega no quadro workspace_event, com o mesmo formato de GET /v1/events:
{
"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:
{ "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:
{
"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
sincepara recuperar os eventos do intervalo, ou recarregue pela API HTTP o que pode ter mudado.