Operatori

14 endpoint-uri. Fiecare cale de mai jos este relativă la URL-ul de bază al API-ului și include deja prefixul /api/v1 — vezi convențiile pentru autentificare, paginare, erori și idempotență.

	Endpoint
GET	`/contact-center/operators`	List contact-centre operators with presence and current state, filterable by state, online and name search
POST	`/contact-center/operators`	Create an operator profile bound to an existing user and return its detailed representation
GET	`/contact-center/operators/{id}`	Fetch one operator with presence, routing settings, skills and queue memberships
PATCH	`/contact-center/operators/{id}`	Update an operator's profile and routing settings; state is not editable here
DELETE	`/contact-center/operators/{id}`	Delete an operator, refusing while they are in a productive state such as on a call
POST	`/contact-center/operators/{id}/calls/{queueCallId}/accept`	Accept a ringing queue offer and bridge the media, reporting connection success separately from acceptance
POST	`/contact-center/operators/{id}/calls/{queueCallId}/reject`	Decline a ringing queue offer, requeue the caller and auto-pause the operator after too many misses
POST	`/contact-center/operators/{id}/heartbeat`	Refresh an operator's presence and return how many seconds until the next heartbeat is due
POST	`/contact-center/operators/{id}/login`	Open an operator session, force the operator to available and return the new session id
POST	`/contact-center/operators/{id}/logout`	Force an operator offline, close their open sessions and clear their presence entry
POST	`/contact-center/operators/{id}/state`	Move an operator into a self-selectable state through the state machine, recording the reason
GET	`/contact-center/operators/{id}/statistics`	Return an operator's live snapshot, or a rolled-up daily summary when from and to are given
POST	`/contact-center/operators/{id}/wrap-up`	Close wrap-up with a disposition, note and callback details, and release the operator back to available
GET	`/contact-center/queue-calls/{queueCallId}/briefing`	§14: the pre-answer briefing

Endpoint-uri

List contact-centre operators with presence and current state, filterable by state, online and name search

GET/contact-center/operators

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.

Parametri de interogare

Nume	Tip	Obligatoriu	Note
`state`	string	—
`online`	boolean	—	default `false`
`search`	string	—

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/contact-center/operators?state=string&online=false" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/operators?state=string&online=false`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/operators?state=string&online=false');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/operators?state=string&online=false",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped array

Exemplu de răspuns, generat din schemă:

json

{
  "data": {},
  "meta": {
    "page": 1,
    "limit": 25,
    "total": 1,
    "pages": 1
  }
}

Create an operator profile bound to an existing user and return its detailed representation

POST/contact-center/operators

Necesită operator.write.
Returns 201, not 200. user_id must reference an existing user row.

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`user_id`	string	da
`display_name`	string	da	max 255 chars
`email`	string \| null	—	email. max 255 chars
`operator_number`	string \| null	—	max 24 chars
`extension_id`	string \| null	—
`supervisor_id`	string \| null	—
`priority`	integer \| null	—	min 0. max 1000
`max_concurrent_calls`	integer \| null	—	min 1. max 10
`wrap_up_seconds`	integer \| null	—	min 0. max 900
`no_answer_timeout_seconds`	integer \| null	—	min 5. max 120
`auto_pause_after_missed`	integer \| null	—	min 0. max 20
`auto_answer`	boolean \| null	—
`can_receive_inbound`	boolean \| null	—
`can_place_outbound`	boolean \| null	—
`is_supervisor`	boolean \| null	—
`language`	string \| null	—	max 16 chars
`languages`	string[] \| null	—
`timezone`	string \| null	—	max 64 chars
`is_active`	boolean \| null	—

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/contact-center/operators" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "user_id": "01JQ0000000000000000000000",
       "display_name": "Support Line",
       "email": "ops@example.com",
       "operator_number": "+40712345678",
       "extension_id": "01JQ0000000000000000000000",
       "supervisor_id": "01JQ0000000000000000000000",
       "priority": 1
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/operators`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "user_id": "01JQ0000000000000000000000",
    "display_name": "Support Line",
    "email": "ops@example.com",
    "operator_number": "+40712345678",
    "extension_id": "01JQ0000000000000000000000",
    "supervisor_id": "01JQ0000000000000000000000",
    "priority": 1
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/operators');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'user_id' => '01JQ0000000000000000000000',
    'display_name' => 'Support Line',
    'email' => 'ops@example.com',
    'operator_number' => '+40712345678',
    'extension_id' => '01JQ0000000000000000000000',
    'supervisor_id' => '01JQ0000000000000000000000',
    'priority' => 1,
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/operators",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "user_id": "01JQ0000000000000000000000",
      "display_name": "Support Line",
      "email": "ops@example.com",
      "operator_number": "+40712345678",
      "extension_id": "01JQ0000000000000000000000",
      "supervisor_id": "01JQ0000000000000000000000",
      "priority": 1
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	JSON object

Erori

Status	Când apare
`403`	Session user lacks the operator.write permission
`422`	Validation failed; user_id and display_name are required

Fetch one operator with presence, routing settings, skills and queue memberships

GET/contact-center/operators/{id}

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`id`	string	da

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/contact-center/operators/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/operators/01JQ0000000000000000000000`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/operators/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/operators/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`404`	No operator with this id in the caller's tenant

Exemplu de răspuns, generat din schemă:

json

{
  "data": {}
}

Update an operator's profile and routing settings; state is not editable here

PATCH/contact-center/operators/{id}

Necesită operator.write.
state is deliberately rejected as an input: it moves only through the state machine, via /state or a supervisor force.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`id`	string	da

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`display_name`	string	—	max 255 chars
`email`	string \| null	—	email. max 255 chars
`extension_id`	string \| null	—
`supervisor_id`	string \| null	—
`priority`	integer \| null	—	min 0. max 1000
`max_concurrent_calls`	integer \| null	—	min 1. max 10
`wrap_up_seconds`	integer \| null	—	min 0. max 900
`no_answer_timeout_seconds`	integer \| null	—	min 5. max 120
`auto_pause_after_missed`	integer \| null	—	min 0. max 20
`auto_answer`	boolean \| null	—
`can_receive_inbound`	boolean \| null	—
`can_place_outbound`	boolean \| null	—
`is_supervisor`	boolean \| null	—
`language`	string \| null	—	max 16 chars
`languages`	string[] \| null	—
`timezone`	string \| null	—	max 64 chars
`is_active`	boolean \| null	—

cURLJavaScriptPHPPython

bash

curl -X PATCH "$CALLAGENT_API_URL/contact-center/operators/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "display_name": "Support Line",
       "email": "ops@example.com",
       "extension_id": "01JQ0000000000000000000000",
       "supervisor_id": "01JQ0000000000000000000000",
       "priority": 1,
       "max_concurrent_calls": 1,
       "wrap_up_seconds": 30
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/operators/01JQ0000000000000000000000`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "display_name": "Support Line",
    "email": "ops@example.com",
    "extension_id": "01JQ0000000000000000000000",
    "supervisor_id": "01JQ0000000000000000000000",
    "priority": 1,
    "max_concurrent_calls": 1,
    "wrap_up_seconds": 30
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/operators/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'display_name' => 'Support Line',
    'email' => 'ops@example.com',
    'extension_id' => '01JQ0000000000000000000000',
    'supervisor_id' => '01JQ0000000000000000000000',
    'priority' => 1,
    'max_concurrent_calls' => 1,
    'wrap_up_seconds' => 30,
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.patch(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/operators/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "display_name": "Support Line",
      "email": "ops@example.com",
      "extension_id": "01JQ0000000000000000000000",
      "supervisor_id": "01JQ0000000000000000000000",
      "priority": 1,
      "max_concurrent_calls": 1,
      "wrap_up_seconds": 30
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	JSON object

Erori

Status	Când apare
`403`	Session user lacks the operator.write permission
`404`	No operator with this id in the caller's tenant
`422`	Validation failed on the operator payload

Delete an operator, refusing while they are in a productive state such as on a call

DELETE/contact-center/operators/{id}

Necesită operator.write.
Acest răspuns nu este împachetat în data.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`id`	string	da

cURLJavaScriptPHPPython

bash

curl -X DELETE "$CALLAGENT_API_URL/contact-center/operators/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/operators/01JQ0000000000000000000000`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/operators/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.delete(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/operators/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	Bare JSON object, not `data`-wrapped

Erori

Status	Când apare
`403`	Session user lacks the operator.write permission
`404`	No operator with this id in the caller's tenant
`409`	The operator is currently on a call

Accept a ringing queue offer and bridge the media, reporting connection success separately from acceptance

POST/contact-center/operators/{id}/calls/{queueCallId}/accept

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.
Always 200 even on failure: if the offer is no longer held by this operator the body carries connected=false and connection_error=offer_no_longer_held.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`id`	string	da
`queueCallId`	string	da

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/contact-center/operators/01JQ0000000000000000000000/calls/01JQ0000000000000000000000/accept" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/operators/01JQ0000000000000000000000/calls/01JQ0000000000000000000000/accept`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/operators/01JQ0000000000000000000000/calls/01JQ0000000000000000000000/accept');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/operators/01JQ0000000000000000000000/calls/01JQ0000000000000000000000/accept",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`404`	The operator or the queue call does not exist in this tenant

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "queue_call_id": null,
    "status": "string",
    "connected": "string",
    "connection_error": "string",
    "briefing": {}
  }
}

Decline a ringing queue offer, requeue the caller and auto-pause the operator after too many misses

POST/contact-center/operators/{id}/calls/{queueCallId}/reject

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.
Rejecting an offer held by someone else is not an error: it returns status=skipped with reason=not_offered_to_operator.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`id`	string	da
`queueCallId`	string	da

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/contact-center/operators/01JQ0000000000000000000000/calls/01JQ0000000000000000000000/reject" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/operators/01JQ0000000000000000000000/calls/01JQ0000000000000000000000/reject`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/operators/01JQ0000000000000000000000/calls/01JQ0000000000000000000000/reject');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/operators/01JQ0000000000000000000000/calls/01JQ0000000000000000000000/reject",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`404`	The operator or the queue call does not exist in this tenant

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "status": "string",
    "reason": "string"
  }
}

Refresh an operator's presence and return how many seconds until the next heartbeat is due

POST/contact-center/operators/{id}/heartbeat

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.
Optional body fields source (default 'api') and connection_id are accepted but never validated.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`id`	string	da

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`connection_id`	string	—

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/contact-center/operators/01JQ0000000000000000000000/heartbeat" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "connection_id": "01JQ0000000000000000000000"
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/operators/01JQ0000000000000000000000/heartbeat`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "connection_id": "01JQ0000000000000000000000"
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/operators/01JQ0000000000000000000000/heartbeat');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'connection_id' => '01JQ0000000000000000000000',
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/operators/01JQ0000000000000000000000/heartbeat",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "connection_id": "01JQ0000000000000000000000"
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`404`	No operator with this id in the caller's tenant

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "ok": true,
    "next_heartbeat_seconds": 30
  }
}

POST/contact-center/operators/{id}/login

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.
Any stale open session is closed first. Optional body field device (default 'api') is unvalidated.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`id`	string	da

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/contact-center/operators/01JQ0000000000000000000000/login" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/operators/01JQ0000000000000000000000/login`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/operators/01JQ0000000000000000000000/login');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/operators/01JQ0000000000000000000000/login",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`404`	No operator with this id in the caller's tenant

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "session_id": null,
    "operator": {}
  }
}

Force an operator offline, close their open sessions and clear their presence entry

POST/contact-center/operators/{id}/logout

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`id`	string	da

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/contact-center/operators/01JQ0000000000000000000000/logout" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/operators/01JQ0000000000000000000000/logout`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/operators/01JQ0000000000000000000000/logout');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/operators/01JQ0000000000000000000000/logout",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`404`	No operator with this id in the caller's tenant

Exemplu de răspuns, generat din schemă:

json

{
  "data": {}
}

Move an operator into a self-selectable state through the state machine, recording the reason

POST/contact-center/operators/{id}/state

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.
Engine-owned states such as ringing and on_call are rejected with 422; an illegal but self-selectable transition is 409.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`id`	string	da

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`state`	`offline` · `available` · `busy` · `ringing` · `on_call` · `wrap_up` …	da
`reason_code`	string \| null	—	max 64 chars
`reason_note`	string \| null	—	max 255 chars

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/contact-center/operators/01JQ0000000000000000000000/state" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "state": "offline"
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/operators/01JQ0000000000000000000000/state`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "state": "offline"
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/operators/01JQ0000000000000000000000/state');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'state' => 'offline',
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/operators/01JQ0000000000000000000000/state",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "state": "offline"
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`404`	No operator with this id in the caller's tenant
`409`	The state machine refused the transition
`422`	Unknown state, or a state only the routing engine may set

Exemplu de răspuns, generat din schemă:

json

{
  "data": {}
}

Return an operator's live snapshot, or a rolled-up daily summary when from and to are given

GET/contact-center/operators/{id}/statistics

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.
The response shape changes with the query: passing from switches it from the realtime snapshot to the historical rollup.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`id`	string	da

Parametri de interogare

Nume	Tip	Obligatoriu	Note
`from`	string	da	date-time
`to`	string	da	date-time

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/contact-center/operators/01JQ0000000000000000000000/statistics?from=%2B40712345678&to=%2B40712345678" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/operators/01JQ0000000000000000000000/statistics?from=%2B40712345678&to=%2B40712345678`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/operators/01JQ0000000000000000000000/statistics?from=%2B40712345678&to=%2B40712345678');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/operators/01JQ0000000000000000000000/statistics?from=%2B40712345678&to=%2B40712345678",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	JSON object

Erori

Status	Când apare
`404`	No operator with this id in the caller's tenant
`422`	from was supplied without a valid to

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "operator_id": null,
    "name": "Support Line",
    "state": "string",
    "state_label": "string",
    "state_reason": "string",
    "state_since": "string",
    "seconds_in_state": {},
    "online": true,
    "offered_today": 1,
    "answered_today": 1,
    "missed_today": 1
  }
}

Close wrap-up with a disposition, note and callback details, and release the operator back to available

POST/contact-center/operators/{id}/wrap-up

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.
Side effect: a disposition flagged schedules_callback writes callback fields onto the queue call.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`id`	string	da

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`queue_call_id`	string \| null	—
`disposition_id`	string \| null	—
`note`	string \| null	—	max 5000 chars
`tags`	string[] \| null	—
`quality_score`	integer \| null	—	min 0. max 100
`first_contact_resolution`	boolean \| null	—
`callback_number`	string \| null	—	max 32 chars
`callback_scheduled_for`	string \| null	—	date-time

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/contact-center/operators/01JQ0000000000000000000000/wrap-up" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "queue_call_id": "01JQ0000000000000000000000",
       "disposition_id": "01JQ0000000000000000000000",
       "quality_score": 1,
       "first_contact_resolution": true,
       "callback_number": "+40712345678",
       "callback_scheduled_for": "2026-01-01T12:00:00+00:00"
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/operators/01JQ0000000000000000000000/wrap-up`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "queue_call_id": "01JQ0000000000000000000000",
    "disposition_id": "01JQ0000000000000000000000",
    "quality_score": 1,
    "first_contact_resolution": true,
    "callback_number": "+40712345678",
    "callback_scheduled_for": "2026-01-01T12:00:00+00:00"
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/operators/01JQ0000000000000000000000/wrap-up');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'queue_call_id' => '01JQ0000000000000000000000',
    'disposition_id' => '01JQ0000000000000000000000',
    'quality_score' => 1,
    'first_contact_resolution' => true,
    'callback_number' => '+40712345678',
    'callback_scheduled_for' => '2026-01-01T12:00:00+00:00',
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/operators/01JQ0000000000000000000000/wrap-up",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "queue_call_id": "01JQ0000000000000000000000",
      "disposition_id": "01JQ0000000000000000000000",
      "quality_score": 1,
      "first_contact_resolution": True,
      "callback_number": "+40712345678",
      "callback_scheduled_for": "2026-01-01T12:00:00+00:00"
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`404`	No operator with this id in the caller's tenant
`422`	Payload invalid, or the queue requires a disposition or the disposition requires a note

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "call_disposition_id": null,
    "operator": {}
  }
}

§14: the pre-answer briefing

GET/contact-center/queue-calls/{queueCallId}/briefing

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.
Not read-only: the first call freezes the assembled caller_history onto the queue call row.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`queueCallId`	string	da

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/contact-center/queue-calls/01JQ0000000000000000000000/briefing" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/queue-calls/01JQ0000000000000000000000/briefing`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/queue-calls/01JQ0000000000000000000000/briefing');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/queue-calls/01JQ0000000000000000000000/briefing",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped array

Erori

Status	Când apare
`404`	No queue call with this id in the caller's tenant

Exemplu de răspuns, generat din schemă:

json

{
  "data": {}
}

Operatori ​

Endpoint-uri ​

List contact-centre operators with presence and current state, filterable by state, online and name search ​

Create an operator profile bound to an existing user and return its detailed representation ​

Fetch one operator with presence, routing settings, skills and queue memberships ​

Update an operator's profile and routing settings; state is not editable here ​

Delete an operator, refusing while they are in a productive state such as on a call ​

Accept a ringing queue offer and bridge the media, reporting connection success separately from acceptance ​

Decline a ringing queue offer, requeue the caller and auto-pause the operator after too many misses ​

Refresh an operator's presence and return how many seconds until the next heartbeat is due ​

Open an operator session, force the operator to available and return the new session id ​

Force an operator offline, close their open sessions and clear their presence entry ​

Move an operator into a self-selectable state through the state machine, recording the reason ​

Return an operator's live snapshot, or a rolled-up daily summary when from and to are given ​

Close wrap-up with a disposition, note and callback details, and release the operator back to available ​

§14: the pre-answer briefing ​

Operatori

Endpoint-uri

List contact-centre operators with presence and current state, filterable by state, online and name search

Create an operator profile bound to an existing user and return its detailed representation

Fetch one operator with presence, routing settings, skills and queue memberships

Update an operator's profile and routing settings; state is not editable here

Delete an operator, refusing while they are in a productive state such as on a call

Accept a ringing queue offer and bridge the media, reporting connection success separately from acceptance

Decline a ringing queue offer, requeue the caller and auto-pause the operator after too many misses

Refresh an operator's presence and return how many seconds until the next heartbeat is due

Open an operator session, force the operator to available and return the new session id

Force an operator offline, close their open sessions and clear their presence entry

Move an operator into a self-selectable state through the state machine, recording the reason

Return an operator's live snapshot, or a rolled-up daily summary when from and to are given

Close wrap-up with a disposition, note and callback details, and release the operator back to available

§14: the pre-answer briefing