Getting Started

This guide explains how to integrate with the Voki API to build applications that use the video call platform.

Prerequisites

• An active tenant account on the Voki platform
• Credentials for a user with the appropriate role (see Authentication)
• HTTP client (curl, Postman, or a library in your preferred language)

Base URL

All API endpoints use the following base URL:

https://voki.avanter.com.br/api/

Step 1: Authentication

The first step is to obtain a JWT token via login.

curl -X POST https://voki.avanter.com.br/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@company.com",
    "password": "your-password",
    "tenant": "tenant-slug"
  }'

The response will contain the access tokens:

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "uuid",
      "name": "Your Name",
      "email": "your-email@company.com",
      "role": "manager"
    }
  }
}

Step 2: Making Authenticated Requests

Include the token and tenant in all requests:

curl -X GET https://voki.avanter.com.br/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "X-Tenant: tenant-slug"

Step 3: Exploring Resources

With the token in hand, you can access all API endpoints according to your user's role:

Role	Access
attendant	Calls, customers, tags, appointments
supervisor	Everything from attendant + departments, sectors, links, export
manager	Full access: users, company, billing, analytics

Example: List Departments

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

Example: List Recent Calls

curl -X GET "https://voki.avanter.com.br/api/v1/calls?page=1&page_size=5&sort_order=desc" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Step 4: Real-Time with WebSocket

For real-time features (queue, presence, notifications), connect via WebSocket:

import { Socket } from "phoenix"

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

// Monitor a department queue
const queueChannel = socket.channel("queue:department_uuid")
queueChannel.join()

queueChannel.on("customer_joined", (payload) => {
  console.log("New customer in queue:", payload)
})

// Track agent presence
const presenceChannel = socket.channel("presence:department_uuid")
presenceChannel.join()

See more details at WebSockets.

Response Format

Success (single object)

{
  "data": {
    "id": "uuid",
    "field": "value"
  }
}

Success (paginated list)

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "page_size": 20,
    "total_pages": 5,
    "total_count": 100
  }
}

Validation Error (422)

{
  "errors": {
    "email": ["can't be blank"],
    "password": ["must be at least 8 characters"]
  }
}

Generic Error (401/403/404)

{
  "errors": {
    "detail": "Unauthorized"
  }
}

Pagination

List endpoints support pagination via query parameters:

Parameter	Type	Default	Description
page	integer	1	Page number (1-based)
page_size	integer	20	Items per page (max 100)
sort_by	string	varies	Field for sorting
sort_order	string	asc	asc or desc

Rate Limiting

Type	Limit
Authentication endpoints (/api/auth/*)	5 req/min
Public endpoints (widget, signup)	30 req/min
Authenticated endpoints	No explicit limit

When the rate limit is exceeded, the API returns 429 Too Many Requests.

SDKs and Libraries

There are currently no official SDKs. The REST API can be consumed directly with any HTTP client. For WebSocket, we recommend the official phoenix library (JavaScript/TypeScript).

npm install phoenix

Next Steps

• Multi-Tenancy - Understand the multi-tenant architecture
• Service Providers - Configure service providers
• Authentication - Complete authentication reference
• WebSockets - Real-time communication