Kavkom API Documentation

Introduction

The Kavkom API lets you add telephony features to your product: order phone numbers and lines, start and monitor calls, embed a phone directly in the browser, and receive real-time call events.

API building blocks

Base URLs & conventions

All requests and responses use JSON. Always send the Content-Type: application/json and Accept: application/json headers.

Authentication

API token X-API-TOKEN & domain_uuid

The Billing and PBX APIs use an API token placed in the X-API-TOKEN header, together with a domain_uuid that identifies the customer domain.

X-API-TOKEN: <your-api-token>

• The token is linked to one or more domains and to a list of authorized routes.
• domain_uuid is a UUID v4. It is sent in the query string for a GET request and in the JSON body for a POST request.
• A token that is not authorized for the requested route, or not linked to the supplied domain_uuid, is rejected.

Access tokens for the WebSocket

The /calls WebSocket connection uses a short-lived access token obtained from a refresh token on the server side.

1. Obtain a refresh token with a protected Bearer token on the server side.
2. Exchange it for an access token with the calls scope and the authorized extensions.

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": "my-app"
}

Response:

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

Ordering resources – Billing API

Extensions and numbers are ordered through the billing system, which creates the order, handles billing and then automatically provisions the resource on the PBX. Extensions are not created directly on the PBX.

Order a line / extension

POST https://client.kavkom.com/api.php with route=order and 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 }
  }'

Successful response:

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

Order a DID number

The order is registered and, once the customer’s identity has been validated, a number is allocated from the stock and provisioned on the PBX with routing to the selected extension.

POST https://client.kavkom.com/api.php with route=order and 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": "Sales line"
  }'

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

List number orders

GET https://client.kavkom.com/api.php with route=order and type=didlist

Required parameter: domain_uuid. Optional parameters: orderby with order_date or accept_date, and asc.

Managing calls – PBX API

List extensions

Returns the extensions configured for a domain, with pagination. A lightweight variant is also available: 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"
}

Start a call, or click-to-call

Originates a call: the PBX first calls the source extension, then bridges it to the destination. The call is automatically recorded and its call_uuid is returned.

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"
}

Hang up a call

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

Expected body: domain_uuid and call_uuid, where call_uuid is returned by the origination endpoint.

Register an extension with SIP

Once the extension has been ordered and provisioned, any SIP device or softphone can register on the PBX. The registration, or REGISTER, tells the switch where the user can be reached. It is required before making or receiving calls.

Credentials

Registration flow

1. The device sends a REGISTER request to the registrar with username@domain.
2. The PBX replies with 401 Unauthorized and a digest challenge.
3. The device sends another REGISTER with the computed digest.
4. On success, the switch returns 200 OK and stores the contact.

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

Build a WebRTC webphone application with SIP.js

This section shows how to embed a phone directly in the browser using an extension’s credentials. The reference implementation uses SIP.js and its SimpleUser helper.

Prerequisites

Step 1 – Retrieve SIP credentials on the server side

Call the extension list endpoint to read the three values required for registration: extension, password and user_context, which corresponds to the domain or realm. Check that the extension is enabled: "true".

Steps 2 & 3 – Register and call from the browser

import { Web } from "sip.js";

// 1) Retrieve credentials from YOUR backend.
// Never call the Kavkom API with the token directly from the browser.
const { extension, password, user_context: domain } = await fetch(
  "/api/my-backend/sip-credentials"
).then((r) => r.json());

// 2) Build the SIP client from those values.
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) Connect + register, then place calls.
await simpleUser.connect(); // triggers onServerConnect -> register()
// await simpleUser.call(sipTarget("33612345678"));
// await simpleUser.hangup();

During a call, the client can handle hold, mute, transfer and the DTMF keypad.

Variant – Originate from the server

Instead of letting the client dial, you can start the call from your backend with the origination endpoint. This is useful for a click-to-call button where the user’s extension should ring first.

Real-time call events – WebSocket

The /calls WebSocket pushes call status in real time for the requested extensions.

Connection

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

• Missing t: the server returns 406, “&t parameter is missing”.
• Missing ext: 406, “&ext parameter is missing”.
• Invalid or expired token: connection rejected with 401 or Invalid token.

Received messages

call event payload

{
  "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

The server sends ping with data: { sentStamp, expiresInSec }. The client must return a pong with the same structure.

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

JavaScript client example

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 – pushing calls & CDRs

From the Kavkom interface, under Advanced → Integrations → Webhook, configure a URL to which Kavkom will send call events. This mechanism is useful for screen-pop, CRM logging, workflow triggering or real-time dashboards.

Configuration parameters

Example received payload

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

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

Endpoint reference

Error codes & troubleshooting

Error format

Billing API:

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

PBX API:

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

Glossary

Kavkom API Documentation – Version 1.0, June 2026.