WebSockets

The Voki API uses Phoenix Channels for real-time communication. All channels require authentication via JWT token.

Connection

Connection URL

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

JavaScript Example

import { Socket } from "phoenix"

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

socket.connect()

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

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

---

Available Channels

Channel	Description	Events
call:{call_id}	Call signaling	signal, ice_candidate, join, leave
queue:{department_id}	Service queue	customer_joined, customer_left, call_assigned
presence:{department_id}	Agent presence	presence_state, presence_diff
notification:{user_id}	Personal notifications	new_notification, appointment_reminder

---

Channel: call:

Channel for WebRTC signaling and video call control.

Events Sent by Client

signal

Sends SDP offer/answer for WebRTC signaling.

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

ice_candidate

Sends ICE candidate for connectivity negotiation.

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

mute

Toggles audio/video mute.

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

Events Received by Client

signal

Receives SDP offer/answer from the SFU server.

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

ice_candidate

Receives ICE candidate from the server.

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

participant_joined

Notifies that a participant has joined the call.

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

participant_left

Notifies that a participant has left the call.

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

call_ended

Notifies that the call has ended.

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

monitor_start / whisper_start / barge_start

Supervision events (received by the agent when a supervisor monitors, whispers, or barges in).

channel.on("whisper_start", (payload) => {
  // payload: { supervisor_id: "...", supervisor_name: "Maria" }
  // The agent can hear the supervisor, but the customer cannot
})

---

Channel: queue:

Channel for monitoring a department's service queue in real time.

Events Received

customer_joined

Customer entered the queue.

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

customer_left

Customer left the queue (gave up or was served).

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

call_assigned

Call assigned to an agent.

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

queue_update

General queue state update.

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

---

Channel: presence:

Channel for tracking online presence of a department's agents. Uses Phoenix Presence for distributed synchronization.

Events Received

presence_state

Complete presence state upon joining the channel.

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("Online agents:", users)
})

presence_diff

Incremental differences (joins/leaves).

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

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

---

Channel: notification:

Channel for user's personal notifications.

Events Received

new_notification

New notification.

channel.on("new_notification", (payload) => {
  // payload: {
  //   type: "call_assigned" | "appointment_reminder" | "system",
  //   title: "New call assigned",
  //   body: "Carlos Ferreira is waiting in Technical Support",
  //   data: { call_id: "..." }
  // }
})

appointment_reminder

Appointment reminder.

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

---

Error Handling

Automatic Reconnection

The Phoenix socket performs automatic reconnection with exponential backoff:

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

Token Expired

When the JWT token expires, the socket will be disconnected. Renew the token and reconnect:

socket.onClose(() => {
  // Check if the token has expired
  if (isTokenExpired(accessToken)) {
    refreshToken().then((newToken) => {
      socket.params.token = newToken
      socket.connect()
    })
  }
})

---

TURN Credentials

To bypass NAT restrictions in WebRTC calls, obtain TURN credentials:

GET /api/v1/turn/credentials

Request Example

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

Success Response (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
  }
}

Note

TURN credentials are temporary (24h TTL) and must be renewed periodically. The public endpoint /api/v1/call/turn-credentials is also available for clients without JWT authentication.