Pour Commencer

Ce guide explique comment s'intégrer à l'API Voki pour construire des applications utilisant la plateforme de visioconférence.

Prérequis

• Un compte tenant actif sur la plateforme Voki
• Les identifiants d'un utilisateur avec le rôle approprié (voir Authentification)
• Un client HTTP (curl, Postman, ou une bibliothèque dans votre langage)

Base URL

Tous les endpoints de l'API utilisent la base URL suivante :

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

Étape 1 : Authentification

La première étape consiste à obtenir un token JWT via la connexion.

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

La réponse contiendra les tokens d'accès :

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "uuid",
      "name": "Votre Nom",
      "email": "votre-email@entreprise.com",
      "role": "manager"
    }
  }
}

Étape 2 : Effectuer des Requêtes Authentifiées

Incluez le token et le tenant dans toutes les requêtes :

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

Étape 3 : Explorer les Ressources

Avec le token en main, vous pouvez accéder à tous les endpoints de l'API selon le rôle de votre utilisateur :

Rôle	Accès
attendant	Appels, clients, tags, rendez-vous
supervisor	Tout ce qu'un attendant peut faire + départements, secteurs, liens, exportation
manager	Accès total : utilisateurs, entreprise, facturation, analytics

Exemple : Lister les Départements

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

Exemple : Lister les Appels Récents

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"

Étape 4 : Temps Réel avec WebSocket

Pour les fonctionnalités en temps réel (file d'attente, présence, notifications), connectez-vous via WebSocket :

import { Socket } from "phoenix"

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

// Surveiller la file d'attente d'un département
const queueChannel = socket.channel("queue:department_uuid")
queueChannel.join()

queueChannel.on("customer_joined", (payload) => {
  console.log("Nouveau client dans la file :", payload)
})

// Suivre la présence des agents
const presenceChannel = socket.channel("presence:department_uuid")
presenceChannel.join()

Consultez les détails dans WebSockets.

Format des Réponses

Succès (objet unique)

{
  "data": {
    "id": "uuid",
    "champ": "valeur"
  }
}

Succès (liste paginée)

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

Erreur de Validation (422)

{
  "errors": {
    "email": ["ne peut pas être vide"],
    "password": ["doit contenir au moins 8 caractères"]
  }
}

Erreur Générique (401/403/404)

{
  "errors": {
    "detail": "Non autorisé"
  }
}

Pagination

Les endpoints de listage supportent la pagination via des paramètres de requête :

Paramètre	Type	Défaut	Description
page	integer	1	Numéro de page (base 1)
page_size	integer	20	Éléments par page (max. 100)
sort_by	string	variable	Champ de tri
sort_order	string	asc	asc ou desc

Rate Limiting

Type	Limite
Endpoints d'authentification (/api/auth/*)	5 req/min
Endpoints publics (widget, signup)	30 req/min
Endpoints authentifiés	Pas de limite explicite

Lorsque le rate limit est dépassé, l'API renvoie 429 Too Many Requests.

SDKs et Bibliothèques

Il n'existe actuellement pas de SDKs officiels. L'API REST peut être consommée directement avec n'importe quel client HTTP. Pour les WebSockets, nous recommandons la bibliothèque officielle phoenix (JavaScript/TypeScript).

npm install phoenix

Prochaines Étapes

• Multi-Tenancy - Comprendre l'architecture multi-tenant
• Fournisseurs - Configurer les fournisseurs de services
• Authentification - Référence complète de l'authentification
• WebSockets - Communication en temps réel