Integrace

Aplikace agentské lišty je JavaScriptový bundle, který se vkládá přímo do webové aplikace CRM. Integrace spočívá v nastavení parametrů pomocí přidání objektu ucsOperator přímo do window objektu prohlížeče a include samotné aplikace ze serveru UCS. Do objektu ucsOperator aplikace doplní metody pro její ovládání.

<div id="ucsOperator">Načítání agentské lišty...</div>
<script type="text/javascript">
window.ucsOperator = {
  api: { hostname: 'ucs.zakaznik.cz', port: 443 },
  renderTo: 'ucsOperator',
  headless: false,
  autologin: true,
  listDevices: true,
  confirmDevice: false,
  crmAutoOpen: true,
  onError: crm.agentAppFailed,
  onConnect: crm.agentAppConnected,
  onCredentials: crm.provideCredentials,
  onUser: crm.userInformations,
  onIdentify: crm.telephoneIdentificatorRequired,
  onIdentifier: crm.identificatorProvided,
  onDevice: crm.telephonePaired,
  onReady: crm.agentAppReady,
  onStateChange: crm.agentStateChanged,
  onCallRinging: crm.callRinging,
  onCallConnect: crm.callConnected,
  onCallHangup: crm.callHangup,
};
</script>
<script src="https://ucs.zakaznik.cz/operator/operator-v4.0.0.js">

Význam parametrů

api: obj (v4.0.0)

Adresa websocket proxy na UCS. Pokud není nastaven, tak se získá z aktuální URL.

window.ucsOperator.api = {
  hostname: string,
  port: string,
  path?: string,
  secure?: boolean,
  ws: {
    hostname?: string,
    port?: string,
    path?: string,
    secure?: boolean
  },
  recording: {...}, // stejné jako ws
  report: {...}, // stejné jako ws
  email: {...}, // stejné jako ws
  template: {...}, // stejné jako ws
}

lang: str (v4.0.0)

Výchozí jazyk (před tím, než se uživatel přihlásí).

renderTo: str (v4.0.0)

ID html tagu, do kterého se aplikace vyrenderuje (default “app”).

headless: bool (v4.0.0)

Pokud je true, pak se vůbec nespustí GUI.

autologin: bool (v4.0.0)

V případě použití akce login s 3. parametrem remeber nastaveným na true dojde k uložení přihlašovacího jména a hesla do cookie, parametr autologin ovlivňuje, zda se pouze vyplní formulář (autologin: false) nebo se provede i přihlášení (autologin: true)

autologout: bool (v4.0.0)

Automaticky odhlásit uživatele pokud dojde k přihlášení stejného uživatele na jiném počítači nebo v jiném okně prohlížeče?

identifyURL: bool (v4.0.0)

Bude automaticky použit identifikátor předaný v URL?

identifyIP: bool (v4.0.0)

Bude použita IP adresa získaná dotazem na server UCS jako identifikátor?

identifyCookie: bool (v4.0.0)

Bude použit identifikátor zadaný uživatelem při předchozím přihlášení?

listDevices: bool (v4.0.0)

Zda se má z UCS získat seznam dostupných telefonů s jejich identifikátory pro vytvoření dropdown menu s výběrem telefonů.

confirmDevice: bool (v4.0.0)

Pokud je parametr true, tak je uživatel vyzván k potvrzení spárovaného telefonu podle zadaného identifikátoru, při nastavení parametru na false, je aplikace spuštěna okamžitě po spárování telefonu.

showDialControl: bool (v4.0.0)

Mají se v horní liště zobrazit ovládací prvky pro ovládání hovorů?

confirmUnload: bool (v4.0.0)

Dotázat se před uzavřením záložky/okna prohlížeče?

notifyWaitingCallers: bool (v4.0.0)

Má se agentům ve stavu ACW nebo AUX zobrazovat systémové upozornění na volající, kteří vstoupili do fronty?

topMenuNameContent: str (v4.0.0)

%name% - zobrazovat jméno agenta
%icon% - zobrazovat ikonu

showBottomMenu: bool (v4.0.0)

Má se zobrazovat spodní lišta v aplikaci?

autoOpenAccountCode: bool (v4.0.0)

Má se po dokončení hovoru otevřít tabulka pro výběr account kódu k hovoru?

audioInputConstraints: AudioInputConstraints (v4.59.0)

Umožňuje vypnout či zapnout modifikaci zvuku z mikrofonu.

interface AudioInputConstraints {
  echoCancellation?: boolean;
  noiseSuppression?: boolean;
  autoGainControl?: boolean;
};

withoutDevice: bool (v4.0.0)

Pokud je parametr true, pak se aplikace se po přihlášení nepokusí párovat telefon.

legacyStartup: bool (v4.32.0)

Pokud je parametr true, pak aplikace nečeká na browser event 'load', ale okamžitě po načtení operator.js dojde k jeho spuštění.

disableIntegratedAutoLogout: bool (v4.32.0)

Pokud je operátorská aplikace integrovaná v jiném systému, který provádí přihlášení pomocí metody ucsOperator.sso('username', 'token', 'SomeSystem') s nastaveným třetím argumentem, pak při zavření záložky/okna prohlížeče dojde k automatickému odhlášení operátora z UCS. Nastavením tohoto parametru na true se automatické odhlašování vypne.

debounceRequests: bool (v4.34.0)

Pokud je tento parametr zapnutý, historie hovorů neodešle dotaz hned po změně filtru, ale vyčká 500 ms jestli nenastane další změna.

onError: fn (v4.0.0)

Callback, který zavolá aplikace v případě chyby, např. nepodaří se připojit k serveru, předá argument:

• message: str - text chyby

window.ucsOperator.onError = function(message) {
  console.log('Something went wrong:', message);
}

onWarning: fn (v4.0.0)

Callback, který zavolá aplikace v případě neobvyklé situace, např. dojde-li k chybě při zpracování události nebo požadavku, předá argument:

• message: str - text varování

onInfo: fn (v4.0.0)

Callback, který zavolá aplikace v případě informační hlášky, např. výsledek požadované změny, předá argument:

• message: str - text informace

onDebug: fn (v4.0.0)

Callback, který zavolá aplikace v případě ladící hlášky, např. oznámení o volání callbacku, předá argument:

• message: str - text ladící hlášky

onMessage: fn (v4.0.0)

Callback, který zavolá aplikace pro zobrazení hlášky agentovi, např. nepodařilo se odhlášení agenta z důvodu limitu ve frontě, předá argument:

• message: obj
  • message: str - zpráva
  • type: enum - typ zprávy
    • success
    • info
    • warning
    • error
  • group: str - druh zprávy
  • data: obj - další data vztahující se ke zprávě

onConnect: fn (v4.0.0)

Callback, který zavolá aplikace po úspěšném připojení k serveru UCS, předá argument:

• version: str - verze aplikace

onCredentials: fn (v4.0.0)

Callback, který zavolá aplikace po v okamžiku kdy požaduje přihlašovací údaje.

onLoginError: fn (v4.0.0)

Callback volaný v případě chyby při přihlášení (např. invalid credentials), předává argumenty:

• code: int - kód chyby
• message: str - chybová hláška

onUser: fn (v4.0.0)

Callback, který aplikace zavolá ve chvíli úspěšného přihlášení a načtení informací o přihlášeném uživateli, předá argument:

• user: obj - parametry právě přihlášeného uživatele

onIdentify: fn (v4.0.0)

Callback, který aplikace zavolá v okamžiku kdy od uživatele požaduje zadání identifikátoru pro spárování telefonu s PC, předá argument:

• identificators: obj - pole objektů se seznamem telefonů a jejich identifikátorů, pokud je parametr listDevices nastaven na true

onIdentifier: fn (v4.0.0)

Callback, který aplikace zavolá v okamžiku získání identifikátoru, předá argument:

• identificator: str - identifikátor PC zadaný v URL, získaný z cookie, zjištěnou IP adresu pomocí serveru UCS nebo zadaný uživatelem

onDevice: fn (v4.0.0)

Callback, který aplikace zavolá v okamžiku kdy dojde ke spárování telefonu s PC, předá argument:

• device: obj - informace o aktuálně spárovaném telefonu

onReady: fn (v4.0.0)

Callback, který zavolá aplikace po úspěšném přihlášení uživatele, předaný argument:

• state (obj)
  • status: enum - stav dostupnosti agenta, stejný jako v onStateChange
  • reason: str - důvod nepřítomnosti agenta
  • call: obj - aktivní hovor na spárovaném telefonu
  • user: obj - informace o přihlášeném uživateli
  • device: obj - informace o spárovaném telefonu
  • auxReasons: obj - důvody nepřítomnosti
  • callReasons: obj - důvody volání (call reason nastavený agentem po ukončení hovoru)
  • queues: obj - dostupné fronty
  • groups: obj - seznam skupin (enum pro group_id)
  • agents: obj - seznam agentů
  • waitingCallers: int - počet čekajících ve frontách
  • now: timestamp - aktuální čas UCS

onStateChange: fn (v4.0.0)

Callback, který zavolá aplikace při změně stavu dostupnosti agenta, předaný argument:

• staus obj
  • status: enum - stav dostupnosti agenta
    • OFFLINE
    • READY
    • ACW
    • AUX
  • reason: str - důvod nepřítomnosti (AUX)

onCallNew: fn (v4.0.0)

Callback, který zavolá aplikace při sestavování odchozího hovoru, předaný argument:

• call: obj

onCallRinging: fn (v4.0.0)

Callback, který zavolá aplikace při příchozím nebo odchozím hovoru, předaný argument:

• call: obj

onCallConnect: fn (v4.0.0)

Callback, který zavolá aplikace při spojení hovoru, předaný argument:

• call: obj

onCallHold: fn (v4.0.0)

Callback, který zavolá aplikace při přidržení hovoru, předaný argument:

• call: obj

onCallResume: fn (v4.0.0)

Callback, který zavolá aplikace při obnovení přidrženého hovoru, předaný argument:

• call: obj

onCallHangup: fn (v4.0.0)

Callback, který zavolá aplikace při ukončení hovoru, předaný argument:

• call: obj

onCallMute: fn (v4.0.0)

Callback, který zavolá aplikace při vypnutí mikrofonu agentem, předaný argument:

• call: obj

onCallUnmute: fn (v4.0.0)

Callback, který zavolá aplikace při zapnutí mikrofonu agentem, předaný argument:

• call: obj

onAgentSuspend: fn (v4.0.0)

Callback, který zavolá aplikace při přerušení obsluhy jedné z front agentem, přeadný argument:

• queueId: int - ID fronty ze které má být agent vyjmut

onAgentResume: fn (v4.0.0)

Callback, který zavolá aplikace při obnovení obsluhy jedné z front agentem, přeadný argument:

• queueId: int - ID fronty do které má být agent vrácen

onWaitingCallersChange: fn (v4.0.0)

Callback, který zavolá aplikace při změně počtu čekajících ve frontách, jejichž členem je agent, předaný argument:

• waitingCallers: int - počet čekajících ve frontě

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)

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ů