REST API

UCS poskytuje backend REST API prostřednictvím služby ucs-api, routing zajišťuje NGINX. Pro přístup je vyžadováno OAuth přihlášení prostřednictvím existujícího uživatele (uživatel musí být členem role, která má oprávnění superuser a uživatel nesmí být public). Pro testování je možné OAuth vypnout v souboru /etc/ucs.api.conf, v sekci [oauth], parametrem enabled = 0.

Komunikační protokol

Volání iniciovaná směrem do UCS REST API jsou realizována s následujícími parametry:

Přenosový protokol: HTTPS
Zabezpečení: OAuth 2.0 (client_credentials, access token)
Architektura rozhraní: REST
Formát dat: JSON
Kódování: UTF-8
URL: https://ucs.example.com/api/v1.0

Úspěšná volání i očekávané chyby jsou potvrzovány odpovědí s HTTP status 2XX. Výjimky:

OAuth vrací HTTP status 400 v případě špatného požadavku nebo 401 v případě špatných credentials
Neočekávané výjimky (exception na straně UCS) vrací HTTP status 500

POST /login/oauth2/token

Pro volání API metod je požadován B2B OAuth token. Metoda pro získání tokenu vyžaduje jako payload client_id, client_secret a grant_type. V odpovědi se vrátí access token, který je platný 1 hodinu (resp. jak je nastaveno v /etc/ucs.api.conf, v sekci [oauth], parametrem expires = 3600).

Příklad získání OAuth tokenu

Request

POST https://ucs.example.com/login/oauth2/token

Content-Type: application/json

{
  "client_id": "jmeno_servisniho_uctu_v_ucs",
  "client_secret": "heslo_servisniho_uctu_v_ucs",
  "grant_type": "client_credentials"
}

Response

200 OK

Content-Type: application/json

{
  "access_token": "AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz",
  "token_type": "Bearer",
  "expires_in": "3610"
}

Další endpointy REST API vyžadují Authorization hlavičku s platným access tokenem.

Příklad volání metody se získaným access tokenem

Request

GET https://ucs.example.com/api/v1.0/status

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Pokud selže pokus o získání OAuth tokenu, pak je vrácen HTTP status 400 nebo 401.

Příklad neúspěšného pokusu o získání access tokenu

Odpověď na špatný požadavek

400 Bad Request

Content-Type: application/json

{
  "error": "invalid_request",
  "error_description": "We support only \"client_credentials\" grant type",
  "error_uri": "https://www.oauth.com/oauth2-servers/access-tokens"
}

Odpověď na špatné credentials

401 Unauthorized

Content-Type: application/json

{
  "error": "invalid_client",
  "error_description": "Invalid username or password",
  "error_uri": "https://www.oauth.com/oauth2-servers/access-tokens"
}

Stav a číselníky

Následující metody poskytují aktuální stav UCS a číselníky pro získání interních ID objektů v UCS, které jsou požadovány jako atributy dalších metod.

Status

GET /api/v1.0/status

Stav systému UCS, SIP trunků a telefonů.

Příklad získání stavu systému UCS

Request

GET https://ucs.example.com/api/v1.0/status

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "trunks": {
    "1": {
      "name": "SIPY",
      "status": 1,
      "rtt": 1
    },
    "2": {
      "name": "external",
      "status": 0,
      "rtt": 0
    }
  },
  "phones": {
    "1": {
      "name": "System",
      "configured": 279,
      "configured_ipphones": 16,
      "configured_softphones": 263,
      "available": 0,
      "available_ipphones": 0,
      "available_softphones": 0,
      "dead": 11,
      "dead_ipphones": 2,
      "dead_softphones": 9,
      "paired": 11,
      "paired_ipphones": 2,
      "paired_softphones": 9
    },
    "3": {
      "name": "Testik",
      "configured": 2,
      "configured_ipphones": 1,
      "configured_softphones": 1,
      "available": 0,
      "available_ipphones": 0,
      "available_softphones": 0,
      "dead": 0,
      "dead_ipphones": 0,
      "dead_softphones": 0,
      "paired": 0,
      "paired_ipphones": 0,
      "paired_softphones": 0
    }
  },
  "ucs": 0,
  "api": 0,
  "postgres": 14,
  "asterisk": 1,
  "light-log": 0,
  "tftp": 1,
  "stunserver": 1,
  "webserver": 3,
  "nats-server": 1
}

Fronty

GET /api/v1.0/queues

Výpis nastavených front (příchozích i odchozích kampaní) a jejich aktuální stav. Metoda neakceptuje žádné parametry. Odpověď je pole asociativních polí.

Příklad získání přehledu front

Request

GET https://ucs.example.com/api/v1.0/queues

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": [
    {
      "id": 74,
      "active": true,
      "group_id": 11,
      "type": 1,
      "number": "10099",
      "name": "NONLIFE CZ",
      "callers_waiting": 0,
      "callers_ringing": 0,
      "callers_talking": 0,
      "agents_idle": 0,
      "agents_ringing": 0,
      "agents_talking": 0,
      "agents_acw": 0,
      "agents_aux": 0,
      "answered": 1567,
      "overflowed": 1,
      "abandoned": 336,
      "talktime": 314549,
      "waittime": 270986,
      "answered_wait_time": 227409.22137379646,
      "answered_in_service": 740,
      "answered_in_work_hours": 0,
      "answered_in_work_and_sl": 0,
      "abandoned_in_threshold": 140,
      "abandoned_in_work_hours": 0,
      "abandoned_in_work_and_sl": 0,
      "abandoned_full": 0,
      "sl": {
        "day": [
          740,
          1763
        ],
        "week": [
          4184,
          9405
        ],
        "month": [
          17929,
          28297
        ],
        "quarter": [
          44922,
          69392
        ]
      },
      "sl_work": {
        "day": [
          0,
          0
        ],
        "week": [
          0,
          0
        ],
        "month": [
          0,
          0
        ],
        "quarter": [
          0,
          0
        ]
      },
      "last_call_enter": 1724428798.475978,
      "last_call_answer": 1724428717.4761183,
      "callers": []
    },
    ...
  ]
}

Skupiny

GET /api/v1.0/groups

Skupiny v UCS slouží pro organizaci nastavení (odráží organizační strukturu společnosti) a řízení přístupu (na základě rolí). Většina objektů (uživatelé, telefony, fronty, atd.) má atribut group_id, který určuje do jaké skupiny daný objek patří. Pokud objekt nemá tento atribut, pak je pro jeho editaci vyžadováno superuser oprávnění. UCS garantuje, že vždy existuje skupina ID 1. Metoda neakceptuje žádné parametry. Odpověď je pole asociativních polí.

Příklad získání číselníku organizačních skupin UCS

Request

GET https://ucs.example.com/api/v1.0/groups

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "System",
      "external_id": null
    },
    {
      "id": 3,
      "name": "  Testik",
      "external_id": "1234"
    },
    {
      "id": 7,
      "name": "  Test2",
      "external_id": "2222"
    },
    {
      "id": 9,
      "name": "  NN - Brokerska",
      "external_id": "broker1"
    },
    {
      "id": 10,
      "name": "  Markuv Servicedesk",
      "external_id": "service1"
    }
  ]
}

Role

GET /api/v1.0/roles

Role je sada oprávnění, která dovoluje uživatelům využívat služby UCS (a případně editovat nastavení). Typickým příkladem role je např. Administrátor, Běžný uživatel, Supervizor, Agent, atp. Metoda neakceptuje žádné parametry. Odpověď je pole asociativních polí.

Příklad získání číselníku uživatelských rolí UCS

Request

GET https://ucs.example.com/api/v1.0/roles

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "group_id": 1,
      "name": "Administrator"
    },
    {
      "id": 6,
      "group_id": 1,
      "name": "Alice"
    },
    {
      "id": 7,
      "group_id": 1,
      "name": "Bob"
    },
    {
      "id": 9,
      "group_id": 10,
      "name": "Bot"
    },
    {
      "id": 8,
      "group_id": 1,
      "name": "Charlie"
    }
  ]
}

Týmy

GET /api/v1.0/teams

Tým je sada nastavení vlastností call centra, nastavují se zde barvy jednotlivých stavů, důvody neodstupnosti agentů, výchozí hodnoty pro členství ve frontách, atd. Metoda neakceptuje žádné parametry. Odpověď je pole asociativních polí.

Příklad získání číselníku týmů call centra UCS

Request

GET https://ucs.example.com/api/v1.0/teams

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": [
    {
      "id": 8,
      "group_id": 1,
      "name": "Markuv Team",
      "note": "Team TEAM TEAM!!!!",
      "aux_reasons": [
        {
          "reason": "Nemám rád šmouly",
          "break": false,
          "color": "ff0000",
          "limit": null,
          "hidden": false
        }
      ],
      "contacts": [],
      "tasks": {
        "person": 0,
        "person_url": null,
        "call": 0,
        "call_url": null,
        "email": 0,
        "email_url": null
      },
      "maximum_assigned_emails": null,
      "default_inbound_priority": 100,
      "default_inbound_acw": false,
      "default_inbound_acw_timeout": null,
      "default_inbound_busy": null,
      "default_inbound_busy_timeout": null,
      "default_outbound_acw": false,
      "default_outbound_acw_timeout": null,
      "default_email_priority": 100,
      "default_email_languages": {
        "cs_CZ": 100,
        "en_US": 100,
        "de_DE": 100,
        "ru_RU": 100
      },
      "default_email_assigned": null,
      "default_task_priority": 100,
      "color_agent_offline": null,
      "color_agent_ready": "188b35",
      "color_agent_acw": "ffda1f",
      "color_agent_aux": "ff9500",
      "color_agent_ringing": "a1ff2e",
      "color_agent_talking": "a1ff29",
      "color_phone_offline": null,
      "color_phone_idle": "00bfff",
      "color_phone_ringing": "ff00ea",
      "color_phone_talking": "ff00ea",
      "breaks_limit": null,
      "transfer_to_agent": false,
      "transfer_to_queue": false,
      "channels": {
        "inbound": false,
        "task": false,
        "email": false,
        "chat": false,
        "dialer": false
      }
    },
    ...
  ]
}

Hovory

UCS poskytuje CDR (Call Detail Records) o proběhlých hovorech. Každý hovor má stringové unikátní ID, které se skládá z UNIX timestampu zahájení hovoru a tečkou odděleným číslem hovoru od restartu komponenty Asterisk.

Informace o hovoru

GET /api/v1.0/call/{uniqueid}

Metoda umožňuje získání všech uložených dat o proběhlém hovoru. Směr hovoru je dán kombinací atributů src_internal a dst_internal. Detailní informace o tom, jak hovor procházel ústřednou je zaznamenána v atributu path. Pokud byl hovor přepojen, pak dst_ atributy odpovídají cílovému číslu. Pozor, pokud přepojí volající, pak je založen další CDR záznam pro daný hovor.

Příklad získání informací o proběhlém hovoru (Call Detail Record)

Request

GET https://ucs.example.com/api/v1.0/call/1723018607.115

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": {
    "price": 0,
    "duration": 524,
    "src_number": "+420776000001",
    "src_name": "",
    "dst_number": "1800",
    "dst_name": " Bob",
    "src_internal": false,
    "dst_internal": true,
    "calldate": "2024-08-07 10:17:04",
    "connected": "2024-08-07 10:17:07",
    "disconnected": "2024-08-07 10:25:51",
    "src_extension_id": null,
    "dst_extension_id": 75,
    "src_user_id": null,
    "dst_user_id": 11,
    "src_type": "trunk",
    "dst_type": "phone",
    "xfer_users": null,
    "trunk_id": null,
    "uniqueid": "1723018607.115",
    "metadata": {
      "ucrm_interaction_id": 30391,
      "outbound_id": 0
    },
    "src_group_id": 1,
    "dst_group_id": 1,
    "pilot_number": "0776000001",
    "ring_time": 4,
    "talk_time": 524,
    "hold_time": 0,
    "cause": 3,
    "recording": true,
    "recording_duration": 523,
    "path": [
      {
        "date": "2024-08-07 10:16:47",
        "type": 1,
        "number": "0776000001",
        "name": "SIPY"
      },
      {
        "date": "2024-08-07 10:17:04",
        "type": 10000,
        "number": "1800",
        "name": "Bob SP"
      },
      {
        "date": "2024-08-07 10:17:04",
        "type": 10711,
        "number": "1800",
        "name": " Bob"
      },
      {
        "date": "2024-08-07 10:17:04",
        "type": 10001,
        "number": "1800",
        "name": "Bob SP"
      },
      {
        "date": "2024-08-07 10:17:07",
        "type": 10002,
        "number": "1800",
        "name": "Bob SP"
      },
      {
        "date": "2024-08-07 10:25:51",
        "type": 10720,
        "number": "0776000001",
        "name": ""
      },
      {
        "date": "2024-08-07 10:25:51",
        "type": 10,
        "number": "0776000001",
        "name": ""
      }
    ]
  }
}

Získání metadat hovoru

Metadata připojená k hovoru je asociativní pole libovolných klíčů a hodnot. Metadata lze získat k aktivnímu hovoru i zpětně po jeho ukončení.

GET /api/v1.0/metadata/{uniqueid}

Příklad získání metadat k aktivnímu nebo proběhlému hovoru

Request

GET https://ucs.example.com/api/v1.0/metadata/1723018607.115

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": {
    "ucrm_interaction_id": 30391,
    "outbound_id": 0
  }
}

Nastavení metadat hovoru

Metoda umožňuje rozdílovou aktualizaci metadat hovoru. Předané klíče se v metadatech hovoru vytvoří nebo přepíší. Pokud stávající klíč metadat neexistuje v payloadu, pak je tento klíč ponechán beze změny. Pro smazání klíče se jeho hodnota nastaví na null. Metoda vrací výsledná metadata hovoru.

POST /api/v1.0/metadata/{uniqueid}

Příklad aktualizace metadat aktivního nebo proběhlého hovoru

Request

POST https://ucs.example.com/api/v1.0/metadata/1723018607.115

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

{
  "outbound_id": null,
  "pokus": "hokus"
}

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": {
    "ucrm_interaction_id": 30391,
    "pokus": "hokus"
  }
}

Sdílená data

Data předávaná z jiných systémů, která se zobrazují na wallboardech, nebo pomocí kterých se řídí směrování hovorů, přehrávání hlášek, atp.

Zobrazení hodnot

GET /api/v1.0/shared/{identificator}

Získání aktuální hodnoty sdílených dat daného identifikátoru.

Příklad získání aktuální hodnoty sdílených dat

Request

GET https://ucs.example.com/api/v1.0/shared/osl_chats

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": {
    "type": "osl",
    "data": {
      "SWS": {
        "OneSolution": {
          "Waiting": 5,
          "Processed": 0
        }
      },
      "KPK": {
        "OneSolution": {
          "Waiting": 2,
          "Doing": 4
        }
      }
    }
  }
}

Aktualizace hodnot

POST /api/v1.0/shared/{identificator}

Přepsání hodnoty sdílených dat daného identifikátoru.

Příklad aktualizace sdílených dat

Request

POST https://ucs.example.com/api/v1.0/shared/osl_chats

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

{
  "type": "osl",
  "data": {
    "SWS": {
      "OneSolution": {
        "Waiting": 4,
        "Processed": 1
      }
    },
    "KPK": {
      "OneSolution": {
        "Waiting": 2,
        "Doing": 4
      }
    }
  }
}

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": null
}

Uživatelé

Synchronizace uživatelských účtů.

Výpis uživatelů

GET /api/v1.0/users

Vrátí seznam uživatelů v UCS jako pole objektů. Metoda nemá žádné parametry.

Příklad získání všech existujících uživatelů v UCS

Request

GET https://ucs.example.com/api/v1.0/users

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": [
    {"id": 1, "name": "admin", "external_id": "asdf"},
    {"id": 10, "name": "Alice", "external_id": null},
    {"id": 11, "name": "Bob", "external_id": "2468"}
  ]
}

Detail uživatele

GET /api/v1.0/user/{user_id}

nebo

GET /api/v1.0/user/external/{external_id}

Metoda vrátí kompletní strukturu atributů objektu uživatele User.

Příklad získání všech atributů uživatelského účtu

Request

GET https://ucs.example.com/api/v1.0/user/external/asdf

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": {
    "id": 1,
    "active": true,
    "external_id": "asdf",
    "group_id": 1,
    "role_id": 1,
    "team_id": null,
    "locale": "en_US",
    "username": "admin",
    "firstname": "null",
    "lastname": null,
    "displayname": "admin",
    ...
  }
}

User

Struktura objektu uživatele:

Klíč	Typ	Význam
id	int	unikátní ID uživatele (primární klíč)
username	str	přihlašovací jméno (case-insensitive)
password	str	heslo v plaintextu (do DB je hashována algoritmem PBKDF2)
locale	enum[str]	jazyk uživatelského rozhraní cs_CZ: český en_US: anglický sk_SK: slovenský
email	str	e-mailová adresa uživatele (může být použita pro přihlášení)
primary_extension	int	ID primární linky uživatele
pin	str	kód pro přístup k hlasové schránce
firstname	str	křestní jméno uživatele
lastname	str	příjmení uživatele
public	bool	servisní účty mají tento atribut nastaven na false
group_id	int	ID organizační skupiny UCS do které uživatel patří
identificator	str	identifikátor uživatele pro funkci User Mobility
external_id	str	identifikátor uživatele v externím IS (pozor, je case-sensitive)
filter_id	int	ID filtru odchozích volání pro volání na externí číslo
number	str	externí číslo na které je uživateli voláno v případě odpárování linky
data	json	libovolná metadata vázaná k uživateli ve formátu asociativního pole
team_id	int	ID týmu call centra do kterého uživatel patří
active	bool	příznak zda je uživatelský účet aktivní
wssip_device_id	int	ID softwarového telefonu
certificate	bool	příznak zda se má uživateli vytvořit klientský SSL certifikát
role_id	int	ID role oprávnění do které uživatel patří
channels	json	aktivní kanály pro funkci Omnichannel
clid_number	str	telefonní číslo volajícího pro externí odchozí hovory

Vytvoření uživatele

POST /api/v1.0/user

Založí uživatele v UCS. Povinné atributy jsou username a group_id (v UCS vždy existuje group ID 1). Jako palyload je v požadavku předán uživatelský objekt User. Návratová hodnota je ID nově založeného uživatele.

Příklad založení nového uživatelského účtu

Request

POST https://ucs.example.com/api/v1.0/user

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

{
  "username": "test",
  "group_id": 1
}

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": 123
}

Interní ID UCS nově založeného účtu je 123.

Aktualizace uživatele

PATCH /api/v1.0/user/{user_id}

nebo

PATCH /api/v1.0/user/external/{external_id}

Aktualizuje atributy uživatelského objektu User. Pokud není atribut v payloadu specifikován, pak je zachována jeho stávající hodnota.

Příklad aktualizace atributů existujícího uživatelského účtu

Request

PATCH https://ucs.example.com/api/v1.0/user/123`

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

{
  "external_id": "T1000",
  "password": "1pokus+Hokus2",
  "team_id": 1,
}

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": null
}

V případě chybné hodnoty některého z atributů, je vráceno asociativní pole s danými atributy.

PATCH https://ucs.example.com/api/v1.0/user/external/T1000`

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

{
  "external_id": "t123456",
  "number": "cislo",
  "filter_id": "PSTN",
}

Chybná hodnota v atributu number a filter_id. Chybně zadané atributy zablokují aktualizaci, tzn. ikdyž je hodnota external_id validní, nedojde k jejímu přepsání.

200 OK

Content-Type: application/json

{
  "success": false,
  "data": {
    "number": "contain invalid character (invalid character \"c\")",
    "filter_id": "value must be integer number"
  }
}

Smazání uživatele

DELETE /api/v1.0/user/{user_id}

nebo

DELETE /api/v1.0/user/external/{external_id}

Vymaže uživatele. V historii hovorů dojde ke zrušení reference, ale záznamy vč. nahrávek zůstanou nedotčeny. Pro deaktivaci uživatele lze alternativně nastavit atribut active na hodnotu false, pak zůstává uživatel v DB, ale nemůže se přihlásit.

Příklad smazání uživatelského účtu

Request

DELETE https://ucs.example.com/api/v1.0/user/external/T1000

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": null
}

Stav členství ve frontách

GET /api/v1.0/queues/agents

Přehled přiřazení všech agentů do obsluhy front kontaktního centra. Odpověď je pole objektů AgentQueues jednotlivých uživatelů . Každý uživatel obsahuje atribut queues, což je pole objektů QueueMembership členství v jednotlivých frontách .

Typy front UCS

Hodnota	Význam
0	Outbound - kampaň odchozích hovorů
1	Inbound - fronta příchozích hovorů
2	Task - fronta tásků µCRM
3	E-mail - fronta zpracování příchozích e-mailů

Příklad získání přehledu přiřazení agentů

Request

GET https://ucs.example.com/api/v1.0/queues/agents

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Admin Ucska",
      "external_id": "asdf",
      "queues": [
        {
          "id": 146,
          "type": 3,
          "priority": 100,
          "suspended": false
        },
        {
          "id": 123,
          "type": 2,
          "priority": 80,
          "suspended": false
        },
        {
          "id": 82,
          "type": 1,
          "priority": 1,
          "suspended": true
        },
        {
          "id": 103,
          "type": 0,
          "priority": 100,
          "suspended": false
        }
      ]
    },
    {
      "id": 11,
      "name": "Bob",
      "external_id": "2468",
      "queues": [
        {
          "id": 234,
          "type": 0,
          "priority": 50,
          "suspended": false
        }
      ]
    },
    {
      "id": 43,
      "name": "Pokus Bezfrontovej",
      "external_id": "nonono",
      "queues": [ ]
    }
  ]
}

Nastavení členství ve frontách

POST /api/v1.0/queues/agents

Hromadná aktualizace přiřazení specifikovaných agentů pro obsluhu front kontaktního centra. Payload požadavku obsahuje pole objektů AgentQueues agentů, pro které má být aktualizováno členství ve frontách. Pokud uživatel není v seznamu, pak jeho členství není upraveno (není smazán ze všech front). Uživatel může být identifikován interním ID UCS (atribut id) nebo externím ID z jiného informačního systému (atribut external_id). Pokud jsou uvedeny oba atributy, pak se použije atribut id a atribut external_id je ignorován.

Členství se nastavuje atributem queues, což je pole objektů QueueMembership všech front, které daný agent obsluhuje. Pokud nemají být modifikovány žádné parametry členství agenta ve frontě, pak stačí do pole v atributu queues předat asociativní pole obsahující pouze id dané fronty. Pro aktualizaci stačí vyplnit pouze atributy, které mají být změněny nebo lze ponechat stávající hodnoty a aktualizace je přeskočena (nezatěžuje se UCS). Pro vymazání členství z fronty se daná fronta vypustí z pole v atributu queues daného uživatele.

Pokud je payload validní, pak je atribut success návratové hodnoty nastaven na true a v atributu data jsou výsledky aktualizace jednotlivých uživatelů (vč. atributu success) a v každém objektu uživatele v atributu queues výsledky aktualizace jeho členství v jednotlivých frontách (opět vč. atributu success).

AgentQueues

Struktura objektu agenta:

Klíč	Typ	Význam
id	int	unikátní ID uživatele (primární klíč)
external_id	str	identifikátor uživatele v externím IS
queues	array	pole členství agenta ve frontách (objekt QueueMembership)

QueueMembership

Struktura objektu členství agenta ve frontě:

Klíč	Typ	Význam
id	int	ID fronty UCS
priority	int	priorita obsluhy interakcí ve frontě (1 nejnižší, 100 nejvyšší)
suspended	bool	při nastavení false je pozastaveno zpracování interakcí ve frontě

Příklad aktualizace členství agentů ve frontách

Request

Pro uživatele admin (ID 1) bude:
- ponechána fronta mailů (ID 146) beze změny
- stejně tak ponechána fronta tásků (ID 123) beze změny
- obnovena obsluha fronty příchozích hovorů (ID 82)
- odstraněn z obsluhy kampaně odchozích hovorů (103)
Uživatel Bob nebude aktualizován (zůstane členem odchozí kampaně ID 234)
Uživatel Pokus Bezfrontovej (externí identifikátor 2468) bude:
- přidán do obsluhy fronty příchozích hovorů (ID 82)
- omylem přidán do neexistující fronty
Pokus o aktualizaci neexistujícího uživatele (ID 0)
Pokus o aktualizaci neexistujícího uživatele (externí identifikátor neexistuje)

POST https://ucs.example.com/api/v1.0/queues/agents

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

[
  {
    "id": 1,
    "queues": [
      {"id": 146},
      {"id": 123, "priority": 80, "suspended": false},
      {"id": 82, "suspended": false}
    ]
  },
  {
    "external_id": "2468",
    "queues": [
      {"id": 82},
      {"id": 0}
    ]
  },
  {
    "id": 0,
    "queues": [ ]
  },
  {
    "external_id": "neexistuje",
    "queues": [ ]
  }
]

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "success": true,
      "queues": [
        {"id": 146, "success": true, "Nothing to change"},
        {"id": 123, "success": true, "Nothing to change"},
        {"id": 82, "success": true, "Agent membership updated"},
        {"id": 103, "success": true, "Agent removed from queue"}
      ]
    },
    {
      "external_id": "2468",
      "success": true,
      "queues": [
        {"id": 82, "success": true, "Agent added into queue"},
        {"id": 0, "success": false, "Unknown queue id"}
      ]
    },
    {
      "id": 0,
      "success": false,
      "error": "Unknown agent id",
      "queues": [ ]
    },
    {
      "external_id": "neexistuje",
      "success": false,
      "error": "Unknown agent external_id",
      "queues": [ ]
    }
  ]
}

µCRM

Synchronizace zákazníků do UCS mikro CRM.

Seznam kontaktních osob

GET /api/v1.0/crm/persons

Metoda akceptuje nepovinné parametry limit a offset v URL.

Návratová hodnota je pole Person objektů.

Příklad získání 50 kontaktních osob s offsetem 100

Request

GET https://ucs.example.com/api/v1.0/crm/persons?limit=50&offset=100

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": [
    {
      "id": 26920,
      "group_id": 1,
      "displayname": "Abrhám Václav",
      "firstname": "Václav",
      "lastname": "Abrhám",
      "external_id": "16943"
    },
    {
      "id": 13270,
      "group_id": 1,
      "displayname": "Adamec Lukáš",
      "firstname": "Lukáš",
      "lastname": "Adamec",
      "external_id": "20451"
    },
    {
      "id": 25677,
      "group_id": 1,
      "displayname": "Albert Antonín",
      "firstname": "Antonín",
      "lastname": "Albert",
      "external_id": "23393"
    },
    ...
  ],
  "total": 26907
}

V µCRM je celkem 26907 osob.

Detail kontaktní osoby

GET /api/v1.0/crm/person/{person_id}

nebo

GET /api/v1.0/crm/person/external/{external_id}

Příklad získání detailu kontaktní osoby z µCRM

Request

GET https://ucs.example.com/api/v1.0/crm/person/59233

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

nebo

GET https://ucs.example.com/api/v1.0/crm/person/external/abc123

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": {
    "id": 59233,
    "group_id": 1,
    "displayname": "Ing. Petr Novák VIP",
    "firstname": "Petr",
    "lastname": "Novák",
    "note": "Pozor, je to převelice důležitý zákoš…",
    "external_id": "abc123",
    "data": {
      "expires": "2025-01-01 00:00:00"
    },
    "contacts": [
      {
        "id": 71615,
        "type": 2,
        "contact": "a@b.cd",
        "label": "e-mail"
      },
      {
        "id": 71616,
        "type": 1,
        "contact": "+420654321987",
        "label": "mobil"
      },
    ],
    "interactions": [ ],
    "companies": [ ],
    "tasks": [ ]
  }
}

Person

Struktura objektu uživatele:

Klíč	Typ	Význam
id	int	unikátní ID osoby (primární klíč)
group_id	int	ID skupiny jejíž je osoba členem
displayname	str	zobrazované jméno osoby
firstname	str	jméno
lastname	str	příjmení
note	str	libovolná poznámka ke kontaktní osobě
external_id	str	identifikátor uživatele v externím IS
data	object	asociativní pole klíč/hodnota pro libovolná data
contacts	array	pole kontaktních údajů (objekt Contact)
interactions	array	historie komunikace s klientem (read-only)
companies	array	společnosti ve kterých je osoba zařazena (read-only)
tasks	array	tickety spojené s danou osobou (read-only)

Contact

Struktura objektu kontaktu:

Klíč	Typ	Význam
id	int	unikátní ID asociace (primární klíč)
type	enum[int]	typ kontaktu 0: obecný kontakt 1: telefonní číslo 2: e-mailová adresa 3: webová URL
contact	str	kontakt (adresa, telefonní číslo, e-mail, URL)
label	str	popis k danému kontaktnímu údaji

Vložení nové osoby

POST /api/v1.0/crm/person

Jako tělo požadavku se předá struktura objektu Person. Je povinný pouze atribut group_id.

Návratová hodnota je ID nově vytvořeného záznamu.

Příklad vložení nové osoby do µCRM

Request

POST https://ucs.example.com/api/v1.0/crm/person

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

{
  "group_id": 1,
  "displayname": "Martin Dvořák",
  "external_id": "321654987",
  "contacts": [
    {
      "type": 1,
      "contact": "+420222333444",
      "label": "kancelář"
    }
  ]
}

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": 123456
}

Interní ID UCS nově založené osoby µCRM je 123456.

Aktualizace existující osoby

PATCH /api/v1.0/crm/person/{person_id}

Jako tělo požadavku se předá struktura objektu Person s atributy, které mají být aktualizovány. Atribut contacts je nepovinný, pokud nemají být aktualizovány kontakty osoby. Pokud je atribut contacts předán, pak jsou kontakty přepsány podle předaného obsahu.

Návratová hodnota metody je prázdná.

Příklad aktualizace dat existující osoby v µCRM

Request

PATCH https://ucs.example.com/api/v1.0/crm/person/123456

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

{
  "firstname": "Martin",
  "lastname": "Dvořák"
}

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": null
}

Smazání osoby

DELETE /api/v1.0/crm/person/{person_id}

Vymaže osobu z UCS.

Návratová hodnota metody je prázdná.

Příklad smazání existující osoby z µCRM

Request

DELETE https://ucs.example.com/api/v1.0/crm/person/123456

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": null
}

Seznam společností

GET /api/v1.0/crm/companies

Kontaktní osoby v µCRM mohou být zastřešeny společností. Metoda akceptuje nepovinné parametry limit a offset v URL. Návratová hodnota je pole Company objektů.

Příklad získání 50 zastřešujících organizací na offsetu 100

Request

GET https://ucs.example.com/api/v1.0/crm/companies?limit=50&offset=100

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

{
  "success": true,
  "data": [
    {
      "id": 5313,
      "group_id": 1,
      "name": "Acme inc.",
      "external_id": "74"
    },
    {
      "id": 2919,
      "group_id": 1,
      "name": "All happy, ltd.",
      "external_id": "13873"
    },
    {
      "id": 1677,
      "group_id": 1,
      "name": "AZ s.r.o.",
      "external_id": "6694"
    },
    ...
  ],
  "total": 10611
}

Celkem je v µCRM 10611 společností.

Detail společnosti

GET /api/v1.0/crm/company/{company_id}

GET /api/v1.0/crm/company/external/{external_id}

Příklad získání detailu společnosti v µCRM

Request

GET https://ucs.example.com/api/v1.0/crm/company/10764

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

nebo

GET https://ucs.example.com/api/v1.0/crm/company/external/ins

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  success: true,
  data: {
    "id: 10764,
    "group_id: 1,
    "name: "INSOFT s.r.o.",
    "external_id": "ins",
    "data": {
      "ico": "04110889"
    },
    "persons": [
      {
        "person_id": 123456,
        "role": "majitel"
      }
    ],
    "tasks": [ ]
  }
}

Company

Struktura objektu společnosti:

Klíč	Typ	Význam
id	int	unikátní ID společnosti (primární klíč)
group_id	int	ID skupiny jejíž je společnost členem
name	str	název společnosti
external_id	str	identifikátor uživatele v externím IS
data	object	asociativní pole klíč/hodnota pro libovolná data
persons	array	pole osob patřících do společnosti (objekt CompanyPerson)
tasks	array	tickety spojené s danou společností (read-only)

CompanyPerson

Struktura objektu asociace osoby do společnosti:

Klíč	Typ	Význam
person_id	int	unikátní ID osoby (objektu Person)
role	str	popis role osoby ve společnosti

Vložení nové společnosti

POST /api/v1.0/crm/company

Jako tělo požadavku se předá struktura objektu Company. Je povinný pouze atribut group_id.

Návratová hodnota je ID nově vytvořeného záznamu.

Příklad vytvoření nové společnosti v µCRM

Request

POST https://ucs.example.com/api/v1.0/crm/company

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

{
  "group_id": 1,
  "name": "Společnost a.s."
}

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": 10765
}

Aktualizace společnosti

PATCH /api/v1.0/crm/company/{company_id}

Jako tělo požadavku se předá struktura objektu Company s atributy, které mají být aktualizovány. Atribut persons je nepovinný, pokud nemají být aktualizovány asociované osoby. Pokud je atribut persons předán, pak jsou osoby přepsány podle předaného obsahu.

Návratová hodnota metody je prázdná.

Příklad úpravy atributů společnosti v µCRM

Request

PATCH https://ucs.example.com/api/v1.0/crm/company/123456

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

{
  "persons": [
    {
      "person_id": 123456,
      "role": "dodavatel"
    },
    {
      "person_id": 123457,
      "role": "jednatel"
    }
  ]
}

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": null
}

Smazání společnosti

DELETE /api/v1.0/crm/company/{company_id}

Vymaže společnost z UCS.

Návratová hodnota metody je prázdná.

Příklad smazání společnosti z µCRM

Request

DELETE https://ucs.example.com/api/v1.0/crm/company/10764

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": null
}

REST API

Komunikační protokol​

OAuth přihlášení​

Stav a číselníky​

Status​

Fronty​

Skupiny​

Role​

Týmy​

Hovory​

Informace o hovoru​

Získání metadat hovoru​

Nastavení metadat hovoru​

Sdílená data​

Zobrazení hodnot​

Aktualizace hodnot​

Uživatelé​

Výpis uživatelů​

Detail uživatele​

User​

Vytvoření uživatele​

Aktualizace uživatele​

Smazání uživatele​

Stav členství ve frontách​

Typy front UCS​

Nastavení členství ve frontách​

AgentQueues​

QueueMembership​

µCRM​

Seznam kontaktních osob​

Detail kontaktní osoby​

Person​

Contact​

Vložení nové osoby​

Aktualizace existující osoby​

Smazání osoby​

Seznam společností​

Detail společnosti​

Company​

CompanyPerson​

Vložení nové společnosti​

Aktualizace společnosti​

Smazání společnosti​

Komunikační protokol

OAuth přihlášení

Stav a číselníky

Status

Fronty

Skupiny

Role

Týmy

Hovory

Informace o hovoru

Získání metadat hovoru

Nastavení metadat hovoru

Sdílená data

Zobrazení hodnot

Aktualizace hodnot

Uživatelé

Výpis uživatelů

Detail uživatele

User

Vytvoření uživatele

Aktualizace uživatele

Smazání uživatele

Stav členství ve frontách

Typy front UCS

Nastavení členství ve frontách

AgentQueues

QueueMembership

µCRM

Seznam kontaktních osob

Detail kontaktní osoby

Person

Contact

Vložení nové osoby

Aktualizace existující osoby

Smazání osoby

Seznam společností

Detail společnosti

Company

CompanyPerson

Vložení nové společnosti

Aktualizace společnosti

Smazání společnosti