WebSockets

A API Voki utiliza Phoenix Channels para comunicação em tempo real. Todos os canais requerem autenticação via token JWT.

Conexão

URL de Conexão

wss://voki.avanter.com.br/socket/websocket?token={jwt_access_token}

Exemplo com JavaScript

import { Socket } from "phoenix"

const socket = new Socket("wss://voki.avanter.com.br/socket/websocket", {
  params: { token: accessToken }
})

socket.connect()

// Entrar em um canal
const channel = socket.channel("queue:department_id", {})

channel.join()
  .receive("ok", (resp) => console.log("Conectado:", resp))
  .receive("error", (resp) => console.log("Erro:", resp))

---

Canais Disponíveis

Canal	Descrição	Eventos
call:{call_id}	Sinalização de chamada	signal, ice_candidate, join, leave
queue:{department_id}	Fila de atendimento	customer_joined, customer_left, call_assigned
presence:{department_id}	Presença de atendentes	presence_state, presence_diff
notification:{user_id}	Notificações pessoais	new_notification, appointment_reminder

---

Canal: call:

Canal para sinalização WebRTC e controle da chamada de vídeo.

Eventos Enviados pelo Cliente

signal

Envia oferta/resposta SDP para sinalização WebRTC.

channel.push("signal", {
  type: "offer",  // "offer" | "answer"
  sdp: "v=0\r\no=- ..."
})

ice_candidate

Envia candidato ICE para negociação de conectividade.

channel.push("ice_candidate", {
  candidate: "candidate:1234567890 1 udp ...",
  sdpMid: "0",
  sdpMLineIndex: 0
})

mute

Alterna mute de áudio/vídeo.

channel.push("mute", { type: "audio", muted: true })
channel.push("mute", { type: "video", muted: true })

Eventos Recebidos pelo Cliente

signal

Recebe oferta/resposta SDP do servidor SFU.

channel.on("signal", (payload) => {
  // payload: { type: "answer", sdp: "v=0\r\n..." }
  peerConnection.setRemoteDescription(new RTCSessionDescription(payload))
})

ice_candidate

Recebe candidato ICE do servidor.

channel.on("ice_candidate", (payload) => {
  peerConnection.addIceCandidate(new RTCIceCandidate(payload))
})

participant_joined

Notifica que um participante entrou na chamada.

channel.on("participant_joined", (payload) => {
  // payload: { user_id: "...", name: "João", role: "attendant" }
})

participant_left

Notifica que um participante saiu da chamada.

channel.on("participant_left", (payload) => {
  // payload: { user_id: "..." }
})

call_ended

Notifica que a chamada foi encerrada.

channel.on("call_ended", (payload) => {
  // payload: { reason: "completed" }
})

monitor_start / whisper_start / barge_start

Eventos de supervisão (recebidos pelo atendente quando um supervisor monitora, sussurra ou intervém).

channel.on("whisper_start", (payload) => {
  // payload: { supervisor_id: "...", supervisor_name: "Maria" }
  // O atendente pode ouvir o supervisor, mas o cliente não
})

---

Canal: queue:

Canal para monitorar a fila de atendimento de um departamento em tempo real.

Eventos Recebidos

customer_joined

Cliente entrou na fila.

channel.on("customer_joined", (payload) => {
  // payload: {
  //   call_id: "...",
  //   customer_name: "Carlos",
  //   position: 3,
  //   queue_size: 5
  // }
})

customer_left

Cliente saiu da fila (desistiu ou foi atendido).

channel.on("customer_left", (payload) => {
  // payload: { call_id: "...", reason: "assigned" | "timeout" | "cancelled" }
})

call_assigned

Chamada atribuída a um atendente.

channel.on("call_assigned", (payload) => {
  // payload: { call_id: "...", user_id: "...", user_name: "João" }
})

queue_update

Atualização geral do estado da fila.

channel.on("queue_update", (payload) => {
  // payload: { queue_size: 4, avg_wait_time: 25, online_agents: 3 }
})

---

Canal: presence:

Canal para rastrear a presença online dos atendentes de um departamento. Utiliza Phoenix Presence para sincronização distribuída.

Eventos Recebidos

presence_state

Estado completo de presença ao entrar no canal.

import { Presence } from "phoenix"

const presence = new Presence(channel)

presence.onSync(() => {
  const users = presence.list((id, { metas }) => ({
    id,
    name: metas[0].name,
    status: metas[0].status,  // "online" | "busy" | "away"
    current_call_id: metas[0].current_call_id
  }))
  console.log("Atendentes online:", users)
})

presence_diff

Diferenças incrementais (joins/leaves).

presence.onJoin((id, current, newPres) => {
  console.log(`${newPres.metas[0].name} ficou online`)
})

presence.onLeave((id, current, leftPres) => {
  console.log(`${leftPres.metas[0].name} ficou offline`)
})

---

Canal: notification:

Canal para notificações pessoais do usuário.

Eventos Recebidos

new_notification

Nova notificação.

channel.on("new_notification", (payload) => {
  // payload: {
  //   type: "call_assigned" | "appointment_reminder" | "system",
  //   title: "Nova chamada atribuída",
  //   body: "Carlos Ferreira está aguardando no Suporte Técnico",
  //   data: { call_id: "..." }
  // }
})

appointment_reminder

Lembrete de agendamento.

channel.on("appointment_reminder", (payload) => {
  // payload: {
  //   appointment_id: "...",
  //   title: "Consulta de acompanhamento",
  //   scheduled_at: "2026-02-20T10:00:00Z",
  //   customer_name: "Carlos Ferreira",
  //   minutes_until: 15
  // }
})

---

Tratamento de Erros

Reconexão Automática

O socket Phoenix realiza reconexão automática com backoff exponencial:

const socket = new Socket(url, {
  params: { token: accessToken },
  reconnectAfterMs: (tries) => [1000, 2000, 5000, 10000][tries - 1] || 10000
})

Token Expirado

Quando o token JWT expira, o socket será desconectado. Renove o token e reconecte:

socket.onClose(() => {
  // Verificar se o token expirou
  if (isTokenExpired(accessToken)) {
    refreshToken().then((newToken) => {
      socket.params.token = newToken
      socket.connect()
    })
  }
})

---

TURN Credentials

Para contornar restrições de NAT em chamadas WebRTC, obtenha credenciais TURN:

GET /api/v1/turn/credentials

Exemplo de Request

curl -X GET https://voki.avanter.com.br/api/v1/turn/credentials \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Resposta de Sucesso (200)

{
  "data": {
    "urls": [
      "turn:voki.avanter.com.br:3478?transport=udp",
      "turn:voki.avanter.com.br:3478?transport=tcp"
    ],
    "username": "1708300800:user123",
    "credential": "abcdef1234567890",
    "ttl": 86400
  }
}

Nota

Credenciais TURN são temporárias (TTL de 24h) e devem ser renovadas periodicamente. O endpoint público /api/v1/call/turn-credentials também está disponível para clientes sem autenticação JWT.