Daktela V6 API: vývoj vlastního agentského rozhraní
Daktela V6 API (application programming interface) umožňuje naintegrovat funkcionality systému Daktela do vlastní aplikace či widgetu. Daktela V6 API (dále jen API) dodržuje REST standardy a komunikace probíhá pomocí HTTP metody. Data jsou serializována do formátu JSON nebo JSONP (více v API dokumentaci). V tomto manuálu je využíváno serializace JSON.
Access token
Pro komunikaci přes Daktela V6 API je nejdříve nutné získat tzv. access token (string), přes který se autorizuje uživatelský požadavek. Access token naleznete v detailu uživatele, případně lze získat i API requestem při přihlášení (viz níže). Součástí všech requestů (kromě přihlášení) musí být platný access token ve tvaru:
/api/v6/endpoint?accessToken={MY_ACCESS_TOKEN}
V opačném případě se vrátí ze serveru response 401 Unauthorized.
Pull data
Endpoint /api/v6/appPullData umožňuje pomocí long pollingu detekovat všechny podstatné události, které nastanou. Kromě dat se vrací i atribut hash, který indentifikuje aktuální stav uživatele. První request se posílá s prázdným atributem hash a server ihned vrátí všechna data a hash. Pro správné fungování pollingu je nutné v každém následujícím requestu posílat také hash vrácený v předchozí response na pull data request. Pokud nastane nějaká událost, server ihned odešle response, jejíž obsahem bude opět hash a data příslušející události. V opačném případě přijde po 15 sekundách response obsahující pouze hash (který je třeba opět poslat v následujícím pull data requestu). Pull data jsou nezbytnou součástí realtime aplikace – detekují aktivity a jejich události (např. příchozí hovor), změnu stavu zařízení, nastavení/zrušení pauzy, přihlášení/odhlášení z front, oznámení atd.
Pull data response vrátí všechna data pouze při prvním requestu s prázdným atributem hash. V následujících requestech s poslaným validním hashem se vrací pouze data (JSON klíče a jim příslušející hodnoty – objekty nebo pole), ve kterých došlo ke změně. Například následující schéma naznačuje událost, kdy začal zvonit příchozí hovor. V pull data response jsou tak pouze klíče activities (zde je příchozí aktivita) a extension (informace o aktuálně přihlášeném uživateli a jeho stavu).
Struktura pull dat je následující:
WhoIm
Endpoint /api/v6/whoim vrací statická data o aktuálně přihlášeném uživateli (v závislosti na access tokenu). Dotazuje se na něj metodou HTTP GET. Pokud není access token validní, vrátí se pouze informace o aktuální verzi systému Daktela V6.
Struktura:
Přihlášení/odhlášení
Pro přihlášení uživatele slouží endpoint /api/v6/login. Jedná se o jediný endpoint, který nevyžaduje access token. V současné době není možné se přes API přihlásit přes OAuth třetích stran (např. Google). Na zmíněný endpoint je třeba poslat HTTP POST request s payloadem
{“username”: “testuser123”, “password”: “SecretPassword”}
V username (string) je uložen indetifikátor uživatele (name), v password (string) pak heslo. V response naleznete data v závislosti na zvolených parametrech a především zde vždy najdete uživatelův access token. Přidáte-li do payloadu atribut only_token (boolean) s hodnotou true, vrátí API v response pouze access token (a nenastaví se cookie). Po úspěšném přihlášení (načtení access tokenu) je vhodné spustit long polling na pull data endpoint, kde naleznete všechna důležitá data.
Odhlásit uživatele je možné přes HTTP GET request na endpoint /api/v6/logout.
Připojit se/odpojit se
Pokud nemá uživatel nastavené statické přihlášení, je nejprve nutné se připojit (přepnout se do Idle stavu). Tuto informaci nese atribut state (string) v objektu extension v pull datech. Je-li state = Session, je třeba se připojit.
K připojení se slouží endpoint /api/v6/usersSession. Stačí poslat HTTP POST request s payloadem
{“setReady”: true}
Response vrátí 200 OK. V případě, že si uživatel vybírá zařízení dynamicky, je nutné v payloadu poslat také číslo (name) zařízení, ke kterému se chce uživatel připojit. Tedy např.
{“setReady”: true, “extension”: “305”, model: "sipDevices"}
nebo
{“setReady”: true, “extension”: “721322422”, model: "externalNumbers"}
Seznam dostupných zařízení vrací endpoint:
/api/v6/getAvailableExtensions?onlyCC=true
Pro odpojení se (přepnutí do Session stavu) je třeba zavolat HTTP POST request opět na endpoint /api/v6/usersSession, tentokrát s payloadem
{“setReady”: false}
Ukázka z webové aplikace Daktela:
state = Session
state = Idle
Přidat/odebrat zařízení
K přidání či odebrání zařízení slouží endpoint /api/v6/usersSession. HTTP POST request s payloadem
{“extension”: “310”}
přihlásí uživatele k zařízení 310.
HTTP POST request s payloadem
{“extension”: {“name”: “310”, “logout”: true}
naopak uživatele od zařízení 310 odhlásí.
Nastavit/zrušit pauzu
Pokud je state (string) v objektu extension v pull datech nastaven na hodnotu Paused, znamená to, že je uživatel na pauze. V takovém případě jsou extension objektu z pull dat nastaveny také atributy id_pause (object? – aktuálně nastavená pauza) a on_pause (datetime? – datum a čas, kdy byla pauza nastavena). V opačném případě jsou tyto atributy null.
Pauzu lze nastavit HTTP POST requestem na endpoint /api/v6/usersSession s payloadem
{“pause”: “mypause”}
kde “mypause” je identifikátor (name) pauzy.
Zrušit pauzu lze obdobně – payload stačí upravit na:
{“pause”: null}
Ukázka z webové aplikace Daktela:
state = Idle
state = Paused
Aktivní/neaktivní zařízení
Z pull dat je možné také vyčíst, zda má uživatel dostupné zařízení. V objektu extension k tomu slouží atribut exten_status (string). Pokud je zařízení dostupné, tak bude v exten_status uloženo Idle. Pokud dostupné není, tak tamtéž bude uloženo Unavailable.
Ukázka z webové aplikace Daktela:
exten_status = Idle
exten_status = Unavailable
Přihlášení/odhlášení z front
Přihlášení či odhlášení z front je opět možné přes endpoint /api/v6/usersSession. HTTP POST request s payloadem
{“queues”: [{“name”: “1234”, “login”: true, “penalty”: “0”}]}
přihlásí uživatele do fronty, jejíž name je 1234.
HTTP POST request s payloadem
{“queues”: [{“name”: “1234”, “login”: false}]}
naopak uživatele z fronty 1234 odhlásí.
Seznam dostupných front lze načíst z whoim endpointu, případně z uživatelského profilu. Z uživatelského profilu se fronty dají načíst HTTP GET requestem na endpoint /api/v6/profiles/{name}/queues (kde name reprezentuje identifikátor (name) profilu uživatele). Identifikátor profilu lze získat z objektu uživatele, který je uložen například v atributu id_agent v objektu extension v pull datech.
Z načtených front je ještě nutné vyfiltrovat ty aktivní a ty, do kterých se uživatel může přihlásit. K tomu slouží atributy deactivated (boolean) a _rdata (objekt) objektu fronty. Deactivated značí, zda je fronta deaktivovaná či nikoliv. V objektu _rdata je mimo jiné atribut login (string) – pokud je jeho hodnota prázdná, tak má uživatel přihlášení do této fronty zakázané (ostatní možné hodnoty jsou auto, manual nebo fix).
Příchozí aktivita
Jak již bylo zmíněno, pull data long polling umožňuje zachytit jakoukoliv událost na ústředně, tedy i příchozí aktivitu (v tomto případě příchozí hovor). Přijde-li příchozí aktivita, tak ji naleznete právě v pull data response – konkrétně v poli activities. Objekt aktivity obsahuje celou řadu atributů, namátkou:
type (string) – typ activity (hovor, email, chat, atd.),
action (string) – aktuální stav activity (čekající, otevřená, odložená, uzavřená),
item (object?) – object s daty příslušejícími specifickému typu activity (viz ActivitiesCall, ActivitiesEmail, ActivitiesWeb, ActivitiesSms, ActivitiesFbm, ActivitiesWap, ActivitiesVbr), (pozn.: nullable),
user (object?) – uživatel, kterému je aktivita přiřazena (případně null, pokud aktivita není přiřazena žádnému uživateli).
Pokud je příchozí aktivita v distribuci (případně pokud se v distribuci nenachází žádný uživatel, na kterého by se aktivita mohla nasměrovat), pak je atribut action prázdný (tzn. action = “”). Aktivita zvoní u aktuálního uživatele, pokud je action = WAIT a user = aktuálně přihlášený uživatel. Pokud je atribut action prázdný nebo je WAIT a atribut user je null, tak příchozí aktivita u uživatele nezvoní (nicméně je stále možné ji přijmout přes čekající aktivity – zvoneček).
Ukázka z webové aplikace Daktela:
action = WAIT and user = currentUser.
action = “” or (action = “WAIT” and user = null)
Přijmout příchozí hovorovou aktivitu je možné HTTP PUT requestem na endpoint dané aktivity (/api/v6/activities/{name}, kde name je identifikátor aktivity) s payloadem
{“action”: “OPEN”, “_exten”: “305”}
_exten (string) udává zařízení (jeho identifikátor - name), které aktivitu bude obsluhovat. Pokud má uživatel právě jedno zařízení nebo pokud se nejedná o hovorovou aktivitu (např. chat), pak je možné atribut _exten v payloadu vynechat. V případě úspěchu vrátí server response 200 OK a pochopitelně se vrátí response z pull data polling requestu, ve které už tentokrát bude atribut action = OPEN u příslušené aktivity.
Podobně je možné odmítnout příchozí aktivitu – HTTP PUT requestem na endpoint /api/v6/activities/{name} s payloadem
{“reject”: true}
Vytvoření odchozí hovorové aktivity
Pro vytočení hovoru je třeba poslat HTTP POST request na endpoint /api/v6/activities s payloadem
{“type“: “CALL“, “number“: “111222333“}
kde number je volané číslo. Tato akce předpokládá, že je uživatel přihlášen v odchozí hovorové frontě.
Ukončení hovoru a uzavření aktivity
Aktuální stav hovoru lze vyčíst z hovorových kanálů. Objekt aktivity vrácený pull daty obsahuje objekt item (viz výše), ve kterém jsou uložena data příslušející danému typu aktivity. V případě hovoru bude v atributu item uložen objekt typu ActivitiesCall. Seznam hovorových kanálů je uložen v poli channels tohoto objektu (pozn.: nullable). Hovorový kanál aktuálního uživatele má v atributu user uložený objekt aktuálního uživatele (je to tedy kanál, pro který platí user = currentUser). Pokud je atribut state hovorového kanálu aktuálního uživatele nastaven na jinou hodnotu než Closed, pak hovor stále probíhá. Ukončit hovor je možné HTTP PUT requestem na endpoint /api/v6/activities/{name} s payloadem
{“hangup”: {“channel“: null}}
kde atribut channel (string?) je kanál, který se má ukončit – pokud je hodnota null, pak se ukončí kanál aktuálního uživatele.
Uzavření aktivity (nejen hovorové) se provádí HTTP PUT requestem na endpoint /api/v6/activities/{name} s payloadem
{“action”: “CLOSE“}
Pokud jsou na frontě právě uzavírané aktivity definovány statusy, pak je nutné je v tomto payloadu poslat také, a to jako pole identifikátorů jednotlivých statusů (atribut name). Tedy například payload
{“action”: “CLOSE“, “statuses“: [“status1”, “status2”]}
poslaný v requestu na výše zmíněný endpoint aktivitu uzavře a současně nastaví její statusy (na statusy s identifikátory (name) status1 a status2).
Práce s chybami vrácenými Daktela V6 API
V případě poslání nevalidního requestu vrátí Daktela API response 400 Bad Request. V těle response se standardně nachází i atribut error. Je-li response status code 2xx, je atribut error v těle response nastavený na null. Naopak je-li response status code 400, tak je v atributu error typicky uložena chybová hláška (lokalizovaná podle hlavičky Accept-Language). Například při pokusu odebrat zařízení (viz výše – HTTP POST request na endpoint /api/v6/usersSession) uživateli přihlášenému v hovorové frontě přijde response se status code 400 a s následujícím tělem
{"result": false,"error": ["Uživatel je přihlášen ve frontách, které vyžadují alespoň jednu linku"]}
Je tak možné zobrazit uživateli i chybové hlášky vrácené Daktela V6 API.
V error atributu může být uloženo pole stringů i objekt. Chybový objekt může mít několik úrovní (např. chybová hláška při ukládání ticketu).