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ç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.conversations:read
/ws/call-sessionSessão de chamadas de voz do atendente.call_session:use
/ws/workflows/{id}/simulateSimulador de um fluxo.workflows:update
/ws/workflows/{id}/ai-builder e /ws/workflows/ai-builderCopiloto 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_ID

Clientes 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/conversations e /ws/call-session aceitam o workspace no parâmetro workspaceId. As demais usam X-Workspace-ID ou o parâmetro workspace_id, como as rotas HTTP. Sem nenhum deles, vale o workspace padrão do usuário.
  • /ws/conversations aceita o parâmetro departmentId para 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.

Did this page help you?