Přeskočit na hlavní obsah

API

Ovládání komponenty​

V okamžiku, kdy se aplikace inicializuje (před zavoláním onConnect callbacku) do objektu window.ucsOperator přidá následující funkce. Funkce je možné volat v následujících stavech:

  • login: CREDENTIALS
  • sso: CREDENTIALS
  • logout: IDENTIFY, DEVICE, READY
  • identificator: IDENTIFY, DEVICE
  • provision: IDENTIFY, DEVICE
  • identify: DEVICE, READY
  • changeStatus: READY
  • suspend: READY
  • resume: READY
  • answer: READY
  • dial: READY
  • hangup: READY
  • transfer: READY
  • hold: READY
  • unhold: READY
  • notify: jakýkoliv
  • state: READY
  • selectRingingSound: READY (v4.43.5)

login (v4.0.0)​

Přihlášení agenta, očekávané argumenty:

  • username: str - uživatelské jméno
  • password: str - heslo
  • remember: bool - mají se přihlašovací údaje uložit do cookie pro příští přihlášení?

sso (v4.0.0)​

Přihlášení uživatele pomocí tokenu, očekávané argumenty:

  • username: str - uživatelské jméno
  • token: str - ověřovací token, viz. SSO
  • provider: str - název aplikace, která provádí přihlášení, pokud v layoutu uživatele existuje tab se stejným názvem, pak je aktivován

Systém do kterého se integruje aplikace předá agenta pro přihlášení pomocí volání:

<script type=”text/javascript”>
window.ucsOperator.sso("prihlasovaci.jmeno", "token", "Jmeno CRM");
</script>

Toto volání je možné provést až na základě onCredentials callbacku z aplikace. Token pro SSO se generuje jako SSHA hash SSO preshared secretu. Secret je počítán následovně:

token = base64_encode(sha1_hash('secret' + 'username' + 'timestamp') + 'username' + 'timestamp')

Pozor! Hodnota z funkce sha1_hash je binární reprezentace výsledného digestu (nikoliv jeho stringová hexadecimální reprezentace).

Po úspěšném přihlášení agenta volá aplikace onReady callback ve kterém předá aktuální stav dostupnosti agenta, informace o případném probíhajícím hovoru, atd.

logout (v4.0.0)​

Odpárování telefonu a odhlášení agenta (bez argumentů).

selectIdentifier (v4.0.0)​

Spárování telefonu s počítačem (aplikací), očekávaný argument:

  • identifier: str - identifikátor telefonu zadaný v UCS na Device

provision (v4.0.0)​

Potvrzení spárovaného telefonu, stažení nastavení aplikace a získání stavu z UCS (bez argumentů).

identify (v4.0.0)​

Výběr jiného telefonu pro spárování bez odhlášení uživatele (bez argumentů).

changeStatus (v4.0.0)​

Změna stavu dostupnosti agenta, očekávané argumenty:

  • status: enum - požadovaný stav
    • OFFLINE
    • READY
    • AUX
    • ACW
  • reason: str - důvod nepřitomnosti (AUX)

Propagace změny stavu agenta z CRM směrem do CC se provádí pomocí volání:

<script type="text/javascript">
// ready
window.ucsOperator.changeStatus("READY");

// AUX (not-ready) s předáním reason
window.ucsOperator.changeStatus("AUX", "Oběd");

// odhlášení z obsluhy front
window.ucsOperator.changeStatus("OFFLINE");
</script>

suspend (v4.0.0)​

Pozastaví obsluhu fronty agentem, očekává argument:

  • queue: int - ID fronty ve které má být pozastavena obsluha

resume (v4.0.0)​

Obnoví obsluhu fronty agentem, očekává argument:

  • queue: int - ID fronty ve které má být obnovena obsluha

answer (v4.0.0)​

Zvedne příchozí hovor (bez argumentů).

dial (v4.0.0)​

Vytočí hovoru (click to dial), očekávané argumenty:

  • number: str - telefonní číslo, které má být na agentově telefonu vytočeno
  • queue: int | "directCall" | "undefined" - ID odchozí fronty (kampaně) pod kterou má být uskutečněn odchozí hovor (nepovinný)
    • "directCall" - nepoužije se odchozí fronta pro vytočení hovoru
    • "undefined" - rozhodnutí o použití odchozí fronty je ponecháno na UCS
  • line: int - ID linky telefonu (device) pomocí které má být hovor uskutečněn
  • data: obj - metadata, která git mají být připojena k hovoru

Funkce click-to-dial z CRM směrem do CC se provádí pomocí volání:

<script type="text/javascript">
window.ucsOperator.dial("0800123456");
</script>

hangup (v4.0.0)​

Zavěšení probíhajícího hovoru (bez argumentů).

Ukončení probíhajícího hovoru z CRM směrem do CC se provádí pomocí volání:

<script type="text/javascript">
window.ucsOperator.hangup();
</script>

transfer (v4.0.0)​

Přepojení hovoru, očekává argument:

  • number: str - telefonní číslo na které má být hovor přepojen

Pokud se nepředá argument number, dojde k přepnutí do transfer režimu (příchozí hovor přepnut do stavu hold) a následně je třeba vytočit číslo jiného agenta (metoda dial).

Pokud se zadá argument number, pak dojde k přepnutí příchozího hovoru do režimu hold a následně dojde k vytočení hovoru pro konzultaci na zadané číslo.

Po úspěšném spojení s agentem (část přepojení kdy se osobě na kterou je hovor přepojován vysvětluje důvod přepojení - konzultace) se přepojení dokončí metodou finishTransfer, která spojí volajícího s cílovým agentem.

finishTransfer (v4.0.0)​

Dokončení přepojení s konzultací (bez argumentů). Předá hovor druhému agentovi, volá se v okamžiku, kdy agenti dokončí konzultaci.

blindTransfer (v4.0.0)​

Přepojení hovoru bez konzultace, očekává jeden povinný argument:

  • number: str - telefonní číslo na které má být hovor přepojen

hold (v4.0.0)​

Přidržení (pozastavení) hovoru (bez argumentů).

unhold (v4.0.0)​

Obnovení pozastaveného hovoru (bez argumentů).

mute (v4.0.0)​

Vypnutí/zapnutí mikrofonu telefonu (bez argumentů). Metoda funguje jako toggle.

notify (v4.0.0)​

Vytvoří aplikační notifikaci, která se zobrazuje buď ve spodní liště aplikace nebo jako například při CREDENTIALS state zpráva typu “Špatné heslo” hned pod inputy přihlašovacího formuláře.

  • title: str - defaultní text notifikace
  • type: str - error, warning, success, info
  • unique: bool - pokud již notifikace existuje, starší se smaže
  • timeout: int - čas, po které notifikace zmizí (null - nikdy)
  • boundState: str - stav, v kterém se aplikace bude zobrazovat (null pro jakýkoliv)
  • group: str - název skupiny notifikací (volitelný)
  • other: obj - další data (např. {values {identificator: ‘cisco’}} pro formátování zprávy “Chybný identifikátor: {identificator}”)

state (v4.0.0)​

Vrátí aktuální stav komponenty (stejný objekt jako v onReady callbacku).

Oproti onReady jsou navíc dostupné atributy: (v4.55.0)

  • ringingSound: 'default' | 'christmas' | 'lovingYou' | 'quest' | 'rush'

setAccountCode (v4.0.0)​

Nastaví důvod volání k hovoru. Očekává následující argumenty:

  • uniqueid: str - unikátní ID hovoru
  • accountCode: str - account kód
  • subAccountCode: str - druhá úroveň account kódu (default null)
  • override: bool - true: přepsat zadaným account kódem, false: připojit zadaný kód k existujícím (default false)

selectRingingSound (v4.43.5)​

Vybere vyzváněcí tón pro softwarový telefon.

Parametry:

  • ringingSound: 'default' | 'christmas' | 'lovingYou' | 'quest' | 'rush'

testRingingSound (v4.55.0)​

stopRingingSoundTest (v4.55.0)​

setTheme (6.18.0)​

Přepíše nastavení téma a znemožní uživateli téma měnit. Slouží zejména pro sjednocení s integrovaným systémem.

Parametry:

  • theme: 'default' | 'dark'

Struktura objektů​

Call (v4.0.0)​

  • called_name: str - jméno volaného
  • called_number: str - číslo volaného
  • called_number_norm: str - číslo volaného ve formátu E.164
  • caller_channel: str - jméno SIP kanálu
  • caller_extension: str - číslo klapky volajícího
  • caller_group_id: int - skupina UCS ve které je zařazen volající
  • caller_internal: bool - volající je vnitřní klapka PBX
  • caller_line_id: int - ID linky telefonu volajícího
  • caller_muted: bool - mikrofon volajícího je vypnut
  • caller_name: str - jméno volajícího
  • caller_number: str - číslo volajícího
  • caller_number_norm: str - číslo volajícího ve formátu E.164
  • caller_type: enum - typ kanálu volajícího
    • line: telefon
    • trunk: trunk
  • caller_user_id: int - ID uživatele klapky
  • caller_username: str - uživatelské jméno UCS uživatele klapky
  • cause: enum - důvod zavěšení hovoru
    • -1: nenastavený (hovor ještě nebyl zavěšen)
    • 0: neznámý
    • 1: obsazeno
    • 2: neplatné číslo
    • 3: zavěsil volající
    • 4: zavěsil volaný
    • 5: odmítnuto
    • 6: nedostupný
    • 7: vyzvednutí (pickup)
    • 8: přepojení (transfer)
  • connected timestamp - čas spojení hovoru
  • connected_channel: str - jméno SIP kanálu na který je hovor spojen
  • connected_group_id: int - skupina UCS ve které je zařazen volaný
  • connected_internal: bool - spojený je vnitřní klapka PBX
  • connected_line_id: int - ID linky telefonu volajícího
  • connected_muted: bool - mikrofon volaného je vypnut
  • connected_name: str - jméno spojeného
  • connected_number: str - číslo na které je hovor spojen
  • connected_number_norm: str - číslo na které je hovor spojen ve formátu E.164
  • connected_type: enum - typ kanálu spojeného
    • line: telefon
    • trunk: trunk
  • connected_user_id: int - ID uživatele spojeného
  • connected_username: str - uživatelské jméno UCS volaného uživatele
  • created timestamp - čas vytvoření hovoru
  • data obj: metadata hovoru, např. to co vrátí serveru UCS při lookupu externí systém jako ID klienta, případně další data
  • direction: enum
    • OUTGOING: odchozí hovor
    • INCOMING: příchozí hovor
  • disconnected timestamp - čas zavěšení hovoru
  • external_id: str - ID získané při lookupu jména volajícího
  • id int - ID aktivního hovoru Pozor, rotuje v rozsahu 1-65535, pro jednoznačnou identifikaci hovoru používejte atribut uniqueid!
  • name str - pokud se podařilo serveru UCS v externím systému dohledat podle čísla jméno volaného/volajícího
  • now timestamp - aktuální čas UCS
  • number: (string) - číslo volaného pro odchozí nebo volajícího pro příchozí hovor
  • outbound_id: int - ID odchozí kampaně
  • recorded: bool - zda byla pořízena nahrávka hovoru
  • state: enum - stav hovoru
    • 0: nový
    • 1: probíhá spojování
    • 2: vyzvání
    • 3: spojen
    • 4: zavěšeno
    • 5: přidržen (hold)
  • subcalls: int - počet vyzvánějících telefonů (v případě hunt-group)
  • uniqueid: str - unikátní ID hovoru

User {#obj-user} (v4.0.0)​

  • acwtime: int - čas strávený v ACW (sekundy)
  • auxtime: int - čas strávený ve stavech nepřipraven (sekundy)
  • auxtimes: obj - časy strávené v jednotlivých časech nepřipraven
    • klíč: str - název AUX
    • hodnota: int - počet sekund v daném čase
  • data: obj - custom data uživatele nadefinovaná v UCS
  • displayname: str - zobrazované jméno uživatele
  • email: str - e-mailová adresa uživatele
  • external_id: str - ID uživatele z externího poskytovatele identit
  • firstname: str - jméno
  • group_id: int - ID skupiny do které uživatel patří
  • id: int - ID uživatele (primární klíč)
  • idletime: int - čas kdy byl uživatel připraven, ale nehovořil (sekundy)
  • in_calls_answered: int - počet spojených příchozích hovorů
  • in_calls_unanswered: int - počet nezodpovězených příchozích hovorů
  • in_ringtime: int - čas vyzvánění příchozích hovorů agenta z front
  • in_talktime: int - prohovořený čas příchozích hovorů agenta z front
  • lastname: str - příjmení
  • lines: array - pole objektů obsahující linky, které má uživatel asociované
  • locale: str - jazyk uživatele
  • number: str - externí telefonní číslo uživatele
  • out_calls_answered: int - počet spojených odchozích hovorů
  • out_calls_unanswered: int - počet nespojených odchozích hovorů
  • out_ringtime: int - čas vyzvánění odchozích hovorů agenta z front
  • out_talktime: int - prohovořený čas odchozích hovorů agenta z front
  • primary_extension: int - ID primární klapky, pokud není použito přihlašování k linkám
  • queues: obj - fronty ve kterých je uživatel zařazen
    • klíč: int - ID fronty
    • hodnota: obj - parametry a hodnoty uživatele ve frontě
  • readytime: int - čas strávený ve stavu připraven (vč. vyzvánění a hovorů)
  • ringtime: int - čas vyzvánění hovorů agenta z front
  • status: enum - stav dostupnosti agenta
    • OFFLINE
    • READY
    • ACW
    • AUX
  • superuser: bool - příznak zda se jedná o superuživatele (admin)
  • talktime: int - prohovořený čas hovorů agenta z front
  • transferred: int - počet přepojených hovorů agenta z front
  • transferred_external: int - počet přepojených hovorů mimo část CC agenta

Queue (v4.0.0)​

  • answered: int - počet spojených hovorů
  • priority: int - priorita agenta ve frontě
  • queue_id: int - ID fronty
  • ringtime: int - čas vyzvánění
  • supervisor: bool - příznak, zda se jedná o supervizora
  • suspended: bool - příznak, zda je agent vyřazen z obsluhy hovorů ve frontě
  • suspendtime: int - čas po který byl agent vyřazen z obsluhy hovorů
  • talktime: int - prohovořený čas
  • team_id: int - ID týmu do kterého agent spadá
  • transferred: int - počet přepojených hovorů agenta z front
  • transferred_external: int - počet přepojených hovorů mimo část CC agenta
  • type: enum - typ fronty:
    • 0: odchozí
    • 1: příchozí
  • unanswered: int - počet nespojených hovorů