API et webhooks

Menu API & webhooks (administrateurs ; option à activer dans Options et intégrations).

#Clé d’API

Créer une clé : elle commence par vxk_ et n’est affichée qu’une fois. Conservez-la dans un coffre-fort de mots de passe. Révoquez-la si elle fuit.

Toutes les requêtes : en-tête Authorization: Bearer vxk_…. Limite : 300 requêtes par minute.

#Exemples

# Faire sonner le poste 100 puis appeler le client (click-to-call)
curl -X POST https://VOTRE-ESPACE/api/v1/calls \
  -H "Authorization: Bearer vxk_…" -H "Content-Type: application/json" \
  -d '{"extension":"100","to":"0612345678"}'

# Journal des appels depuis une date
curl "https://VOTRE-ESPACE/api/v1/cdr?since=2026-01-01&pageSize=100" -H "Authorization: Bearer vxk_…"

# Appels en cours, numéros, postes
curl https://VOTRE-ESPACE/api/v1/calls/live   -H "Authorization: Bearer vxk_…"
curl https://VOTRE-ESPACE/api/v1/numbers      -H "Authorization: Bearer vxk_…"
curl https://VOTRE-ESPACE/api/v1/extensions   -H "Authorization: Bearer vxk_…"

# Demande de rappel (option Rappels)
curl -X POST https://VOTRE-ESPACE/api/v1/callbacks \
  -H "Authorization: Bearer vxk_…" -H "Content-Type: application/json" \
  -d '{"phone":"0612345678","targetType":"queue","targetId":"<id>"}'

La documentation complète (OpenAPI) et les SDK sont dans le Portail développeurs de votre espace.

#Webhooks

Déclarez une adresse HTTPS : elle reçoit un POST JSON à chaque événement.

Exemple call.completed :

{ "event": "call.completed", "createdAt": "…",
  "data": { "uuid": "…", "direction": "INBOUND", "from": "+33611…", "to": "101", "did": "+33188…",
            "startedAt": "…", "answeredAt": "…", "endedAt": "…", "duration": 75, "billsec": 62,
            "hangupCause": "NORMAL_CLEARING", "recorded": true, "costCents": 0 } }

Vérifiez la signature : l’en-tête X-VoxNova-Signature: sha256=… est un HMAC-SHA256 du corps brut avec le secret affiché dans l’interface. Rejetez les requêtes dont la signature ne correspond pas.

#Dans vos scénarios

Les blocs Requête HTTP et Notification d’un scénario d’appel interrogent ou préviennent vos outils pendant l’appel.