Documentation API

Introduction

L’API Kavkom permet d’ajouter des fonctionnalités téléphoniques à votre produit : commander des numéros et des lignes, lancer et superviser des appels, intégrer un téléphone directement dans le navigateur et recevoir les événements d’appel en temps réel.

Les briques de l’API

URLs de base & conventions

Toutes les requêtes et réponses sont en JSON. Envoyez systématiquement les en-têtes Content-Type: application/json et Accept: application/json.

Authentification

Jeton API X-API-TOKEN & domain_uuid

Les API Billing et PBX utilisent un jeton API placé dans l’en-tête X-API-TOKEN, ainsi qu’un domain_uuid qui identifie le domaine client.

X-API-TOKEN: <votre-jeton-api>

• Le jeton est rattaché à un ou plusieurs domaines et à une liste de routes autorisées.
• domain_uuid est un UUID v4. Il est transmis en query string pour un GET et dans le corps JSON pour un POST.
• Un jeton non autorisé pour la route demandée, ou non lié au domain_uuid, est rejeté.

Jetons d’accès pour le WebSocket

La connexion WebSocket /calls utilise un access token de courte durée, obtenu via un refresh token côté serveur.

1. Obtenez un refresh token avec un jeton Bearer protégé côté serveur.
2. Échangez-le contre un access token avec le scope calls et les extensions autorisées.

POST https://live.kavkom.com/api/auth/acquire-access
Authorization: Bearer <refresh-token>
Content-Type: application/json

{
  "userUuid": "<user-uuid>",
  "extensions": [1001],
  "scope": "calls",
  "application": "mon-app"
}

Réponse :

{ "token": "<access-token>", "expiresAt": "<date-ISO>" }

Commander des ressources – API Billing

Les extensions et les numéros se commandent via le système de facturation, qui crée la commande, gère la facturation puis provisionne automatiquement la ressource sur le PBX. On ne crée pas d’extension directement sur le PBX.

Commander une ligne / extension

POST https://client.kavkom.com/api.php avec route=order et type=line

curl -X POST "https://client.kavkom.com/api.php" \
  -H "X-API-TOKEN: <token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "route": "order",
    "type": "line",
    "domain_uuid": "ddcfeb62-110f-4bd7-b7a9-965e1a78295f",
    "options": { "starter": 2 }
  }'

Réponse de succès :

{ "invoiceid": 10231, "order_number": "0123456789" }

Commander un numéro DID

La commande est enregistrée puis, lorsque l’identité du client est validée, un numéro est attribué depuis le stock et provisionné sur le PBX avec un routage vers l’extension choisie.

POST https://client.kavkom.com/api.php avec route=order et type=did

curl -X POST "https://client.kavkom.com/api.php" \
  -H "X-API-TOKEN: <token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "route": "order",
    "type": "did",
    "domain_uuid": "ddcfeb62-110f-4bd7-b7a9-965e1a78295f",
    "country": "FR",
    "location": "Paris",
    "extension": "901",
    "description": "Ligne commerciale"
  }'

{
  "status": "success",
  "return": { "id": 152, "accepted": true }
}

Lister les commandes de numéros

GET https://client.kavkom.com/api.php avec route=order et type=didlist

Paramètre requis : domain_uuid. Paramètres optionnels : orderby avec order_date ou accept_date, et asc.

Gérer les appels – API PBX

Lister les extensions

Retourne les extensions configurées d’un domaine, avec pagination. Une variante allégée existe : GET /api/pbx/v1/extension/list_limited.

GET https://api.kavkom.com/api/pbx/v1/extension/list

curl -X GET "https://api.kavkom.com/api/pbx/v1/extension/list?domain_uuid=ddcfeb62-110f-4bd7-b7a9-965e1a78295f" \
  -H "X-API-TOKEN: <token>" \
  -H "Accept: application/json"

{
  "data": [
    {
      "extension_uuid": "48b0d200-2b31-4211-a3d7-b41f87abbcbb",
      "domain_uuid": "ddcfeb62-110f-4bd7-b7a9-965e1a78295f",
      "extension": "901",
      "password": "aB3xY9zK",
      "user_context": "client.kavkom.com",
      "enabled": "true"
    }
  ],
  "success": true,
  "message": "Action completed successfully"
}

Lancer un appel, ou click-to-call

Origine un appel : le PBX appelle d’abord l’extension source, puis la met en relation avec la destination. L’appel est enregistré automatiquement et son call_uuid est renvoyé.

POST https://api.kavkom.com/api/pbx/v1/active_call/call

curl -X POST "https://api.kavkom.com/api/pbx/v1/active_call/call" \
  -H "X-API-TOKEN: <token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "domain_uuid": "ddcfeb62-110f-4bd7-b7a9-965e1a78295f",
    "src": "901",
    "destination": "33612345678",
    "auto_answer": "true"
  }'

{
  "success": true,
  "message": "Action completed successfully",
  "call_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recording": "+OK"
}

Raccrocher un appel

POST https://api.kavkom.com/api/pbx/v1/active_call/kill

Corps attendu : domain_uuid et call_uuid, le call_uuid étant renvoyé par l’origination.

Enregistrer une extension en SIP

Une fois l’extension commandée et provisionnée, tout appareil SIP ou softphone peut s’enregistrer sur le PBX. L’enregistrement, ou REGISTER, indique au switch où joindre l’utilisateur. Il est requis avant d’émettre ou de recevoir un appel.

Identifiants

Déroulé de l’enregistrement

1. L’appareil envoie un REGISTER au registrar avec username@domain.
2. Le PBX répond 401 Unauthorized avec un challenge digest.
3. L’appareil renvoie REGISTER avec le digest calculé.
4. En cas de succès, le switch renvoie 200 OK et stocke le contact.

SIP Username : 901
Password     : aB3xY9zK
SIP Domain   : client.kavkom.com
Registrar    : client.kavkom.com
Transport    : TLS
Port         : 5061
Expiry       : 3600

Construire une application webphone WebRTC avec SIP.js

Cette section montre comment intégrer un téléphone directement dans le navigateur à partir des identifiants d’une extension. La référence d’implémentation utilise SIP.js et son assistant SimpleUser.

Prérequis

Étape 1 – Récupérer les identifiants SIP côté serveur

Appelez l’endpoint de liste des extensions pour lire les trois valeurs nécessaires à l’enregistrement : extension, password et user_context, qui correspond au domaine ou realm. Vérifiez que l’extension est enabled: "true".

Étape 2 & 3 – Enregistrer et appeler depuis le navigateur

import { Web } from "sip.js";

// 1) Récupérer les identifiants depuis VOTRE backend.
// Ne jamais appeler l'API Kavkom avec le jeton directement depuis le navigateur.
const { extension, password, user_context: domain } = await fetch(
  "/api/mon-backend/sip-credentials"
).then((r) => r.json());

// 2) Construire le client SIP à partir de ces valeurs.
const sipTarget = (number) => `sip:${number}@${domain}`;
const simpleUser = new Web.SimpleUser(`wss://${domain}/`, {
  aor: sipTarget(extension),
  media: { remote: { audio: document.querySelector("#remoteAudio") } },
  userAgentOptions: {
    authorizationUsername: extension,
    authorizationPassword: password,
  },
  delegate: {
    onServerConnect: () => simpleUser.register(),
    onCallReceived: () => simpleUser.answer(),
  },
});

// 3) Connexion + enregistrement, puis appels.
await simpleUser.connect(); // déclenche onServerConnect -> register()
// await simpleUser.call(sipTarget("33612345678"));
// await simpleUser.hangup();

Pendant un appel, le client peut gérer la mise en attente, le micro, le transfert et le clavier DTMF.

Variante – Originer depuis le serveur

Plutôt que de laisser le client composer, vous pouvez démarrer l’appel depuis votre backend avec l’endpoint d’origination. C’est utile pour un bouton click-to-call où l’extension de l’utilisateur doit sonner en premier.

Événements d’appel en temps réel – WebSocket

Le WebSocket /calls pousse l’état des appels en temps réel pour les extensions demandées.

Connexion

WSS wss://live.kavkom.com/calls?t=<access-token>&ext=1001

• t manquant : le serveur répond 406, « &t parameter is missing ».
• ext manquant : 406, « &ext parameter is missing ».
• Token invalide ou expiré : connexion rejetée avec 401 ou Invalid token.

Messages reçus

Charge utile d’un événement call

{
  "event": "call",
  "data": {
    "callUuid": "abc-123",
    "state": "active",
    "direction": "inbound",
    "number": "380501234567",
    "presenceId": "1001@contact.example.kavkom.com",
    "createdEpoch": 1710763200,
    "answeredEpoch": 1710763205,
    "duration": 120
  }
}

Ping / Pong

Le serveur envoie ping avec data: { sentStamp, expiresInSec }. Le client doit renvoyer un pong de même structure.

{ "event": "pong", "data": { "sentStamp": 1710763200000, "expiresInSec": 60 } }

Exemple client JavaScript

const ws = new WebSocket(
  `wss://live.kavkom.com/calls?t=${token}&ext=1001`
);

ws.onmessage = (msg) => {
  const { event, data } = JSON.parse(msg.data);
  if (event === "call") console.log(data.state, data.direction, data.number);
  if (event === "ping") ws.send(JSON.stringify({ event: "pong", data }));
};

Webhooks – push des appels & CDR

Depuis l’interface Kavkom, dans Advanced → Integrations → Webhook, configurez une URL vers laquelle Kavkom enverra les événements d’appel. Ce mécanisme est utile pour le screen-pop, le log dans un CRM, le déclenchement de workflows ou les tableaux de bord temps réel.

Paramètres de configuration

Exemple de payload reçu

POST /webhooks/calls HTTP/1.1
Authorization: Bearer <votre-cle>
Content-Type: application/json

{
  "event": "cdr",
  "callUuid": "a1b2c3d4-...-ef1234567890",
  "direction": "outbound",
  "number": "33612345678",
  "state": "finished",
  "duration": 120
}

Référence des endpoints

Codes d’erreur & dépannage

Forme des erreurs

API Billing :

{ "status": "error", "message": "Fields required: domain_uuid, options" }

API PBX :

{
  "error": true,
  "message": "Model is not valid",
  "validationErrors": { "extension": "The extension field is required." }
}

Glossaire

Documentation API Kavkom – Version 1.0, juin 2026.