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:

CODE

/api/v6/endpoint?accessToken={MY_ACCESS_TOKEN}

V opačném případě se vrátí ze serveru response 401 Unauthorized.

Pull Data

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í:

activities – otevřené/čekající aktivity,
extension – informace o uživateli a jeho stavu,
queues – fronty, do kterých je uživatel přihlášen,
missedChannels – počty zmeškaných aktivit,
announcements – oznámení,
reloadUser – přepínač upozorňující, že je třeba znovu načíst statická whoim data (viz níže).

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:

user – aktuálně přihlášený uživatel,
queues – fronty, na které má uživatel práva,
pauses – pauzy, do kterých může být uživatel přihlášen.

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

CODE

{“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

CODE

{“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ř.

CODE

{“setReady”: true, “extension”: “305”, model: "sipDevices"}
nebo
{“setReady”: true, “extension”: “721322422”, model: "externalNumbers"}

Seznam dostupných zařízení vrací endpoint:

CODE

 /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

CODE

{“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

CODE

{“extension”: “310”}

přihlásí uživatele k zařízení 310.

HTTP POST request s payloadem

CODE

{“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

CODE

{“pause”: “mypause”}

kde “mypause” je identifikátor (name) pauzy.

Zrušit pauzu lze obdobně – payload stačí upravit na:

CODE

{“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

CODE

{“queues”: [{“name”: “1234”, “login”: true, “penalty”: “0”}]}

přihlásí uživatele do fronty, jejíž name je 1234.

HTTP POST request s payloadem

CODE

{“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

CODE

{“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

CODE

{“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

CODE

{“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

CODE

{“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

CODE

{“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

CODE

{“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

CODE

{"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).