WebSockets

La API Voki utiliza Phoenix Channels para comunicación en tiempo real. Todos los canales requieren autenticación vía token JWT.

Conexión

URL de Conexión

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

Ejemplo con JavaScript

import { Socket } from "phoenix"

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

socket.connect()

// Ingresar a un canal
const channel = socket.channel("queue:department_id", {})

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

---

Canales Disponibles

Canal	Descripción	Eventos
call:{call_id}	Señalización de llamada	signal, ice_candidate, join, leave
queue:{department_id}	Cola de atención	customer_joined, customer_left, call_assigned
presence:{department_id}	Presencia de agentes	presence_state, presence_diff
notification:{user_id}	Notificaciones personales	new_notification, appointment_reminder

---

Canal: call:

Canal para señalización WebRTC y control de la videollamada.

Eventos Enviados por el Cliente

signal

Envía oferta/respuesta SDP para señalización WebRTC.

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

ice_candidate

Envía candidato ICE para negociación de conectividad.

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

mute

Alterna el silenciamiento de audio/video.

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

Eventos Recibidos por el Cliente

signal

Recibe oferta/respuesta SDP del servidor SFU.

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

ice_candidate

Recibe candidato ICE del servidor.

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

participant_joined

Notifica que un participante ingresó a la llamada.

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

participant_left

Notifica que un participante salió de la llamada.

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

call_ended

Notifica que la llamada fue finalizada.

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

monitor_start / whisper_start / barge_start

Eventos de supervisión (recibidos por el agente cuando un supervisor monitorea, susurra o interviene).

channel.on("whisper_start", (payload) => {
  // payload: { supervisor_id: "...", supervisor_name: "Maria" }
  // El agente puede escuchar al supervisor, pero el cliente no
})

---

Canal: queue:

Canal para monitorear la cola de atención de un departamento en tiempo real.

Eventos Recibidos

customer_joined

El cliente ingresó a la cola.

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

customer_left

El cliente salió de la cola (desistió o fue atendido).

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

call_assigned

Llamada asignada a un agente.

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

queue_update

Actualización general del estado de la cola.

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

---

Canal: presence:

Canal para rastrear la presencia en línea de los agentes de un departamento. Utiliza Phoenix Presence para sincronización distribuida.

Eventos Recibidos

presence_state

Estado completo de presencia al ingresar al 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("Agentes en línea:", users)
})

presence_diff

Diferencias incrementales (ingresos/salidas).

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

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

---

Canal: notification:

Canal para notificaciones personales del usuario.

Eventos Recibidos

new_notification

Nueva notificación.

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

Recordatorio de cita.

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
  // }
})

---

Manejo de Errores

Reconexión Automática

El socket Phoenix realiza reconexión automática con backoff exponencial:

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

Token Expirado

Cuando el token JWT expira, el socket será desconectado. Renueve el token y reconéctese:

socket.onClose(() => {
  // Verificar si el token expiró
  if (isTokenExpired(accessToken)) {
    refreshToken().then((newToken) => {
      socket.params.token = newToken
      socket.connect()
    })
  }
})

---

Credenciales TURN

Para sortear restricciones de NAT en llamadas WebRTC, obtenga credenciales TURN:

GET /api/v1/turn/credentials

Ejemplo de Request

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

Respuesta Exitosa (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

Las credenciales TURN son temporales (TTL de 24h) y deben renovarse periódicamente. El endpoint público /api/v1/call/turn-credentials también está disponible para clientes sin autenticación JWT.