Tempo real (WebSockets)
As conexões WebSocket que mantêm conversas, chamadas e fluxos atualizados, e como autenticá-las.
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, 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. | conversations:read |
/ws/call-session | Sessão de chamadas de voz do atendente. | call_session:use |
/ws/workflows/{id}/simulate | Simulador de um fluxo. | workflows:update |
/ws/workflows/{id}/ai-builder e /ws/workflows/ai-builder | Copiloto que monta um fluxo existente ou um novo. | workflows:update e workflows:create |
Autenticação
A conexão usa o mesmo token de login das rotas HTTP. Como navegadores não enviam cabeçalhos ao abrir um WebSocket, o token pode ir no parâmetro token da URL:
wss://api.vozkoia.com/ws/conversations?token=SEU_ACCESS_TOKEN&workspaceId=SEU_WORKSPACE_IDClientes que não são navegadores podem enviar o cabeçalho Authorization: Bearer SEU_ACCESS_TOKEN, como nas chamadas HTTP, e assim evitar que o token apareça em URLs e registros.
O token é conferido ao abrir a conexão; ao reconectar, use um token válido, renovado se preciso. A chave de API do workspace não abre conexões WebSocket.
Workspace e departamento
/ws/conversationse/ws/call-sessionaceitam o workspace no parâmetroworkspaceId. As demais usamX-Workspace-IDou o parâmetroworkspace_id, como as rotas HTTP. Sem nenhum deles, vale o workspace padrão do usuário./ws/conversationsaceita o parâmetrodepartmentIdpara filtrar a caixa de entrada por um departamento.
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 e, ao reconectar, recarregue pela API HTTP o que pode ter mudado no intervalo.
Updated 17 days ago