Belső interfész dokumentáció

A programozói interfésszel kapcsolatos alapvető információink:

ez nem egy klasszikus API
nincs hozzá kimerítő részletességű dokumentáció
nincs verziózva, és külön értesítés nélkül bármikor megváltozhat (természetesen igyekszünk értesítést küldeni a változásokról)
A jelenlegi működés fix, tehát fejlesztési igényeket nem tudunk befogadni rá

Általános tudnivaló az interfész használatához

Az interfész HTTPS fölött JSON üzenetekben kommunikál. Alapvetően POST kéréseket használunk. A hívható végpontok a cég adott domainje alatt vannak, a https://cegnev.comnica.cc/api névtér alatt.

Payload formátum

Általánosan minden backend végpontunk a következő JSON formátumot várja:

{
    "rq_sent":"2019-10-07 09:37:49.700+0000", /* A request elküldésének timestampje a kliens szerint */
    "payload":{}                             /* A tényleges kérés */
}

A továbbiakban a requestek leírásakor csak a payload formátumára fogunk kitérni, amennyiben az üres, akkor egy üres JSON objektumot („{}”) kell küldenie a hívó félnek.

Általános válasz formátum:

{
    "res_sent":"2019-10-07 09:37:49.971653+0000", /* A szerver szerint a válasz kiküldésének timestampje */
    "rq_rcvd": "2019-10-07 09:37:49.926506+0000", /* A szerver ekkor kapta meg a kérést */
    "payload":{}                                  /* A tényleges válasz */
}

Minden sikeres kérésre adott válasz 200-as HTTP státuszkódot kap és a fenti formátumú keretbe van csomagolva.

A továbbiakban a válaszok írásakor csak a payload formátumára fogunk kitérni, amennyiben az üres, akkor a szerver egy üres JSON objektumot küld („{}”) küld.

Hibák

400 Bad Request

A válasz JSON formátumú és az általános válasz formátumnál ismeretett wrapperbe van csomagolva. A payload a következő jellegű:

{
    "errors": [
        {
            "code": "BAD_DATA",
            "parameters": {
                "username": "Foo"
            },
            "field_name": null,
            "global": true
        },
        {
            "code": "ALREADY_EXISTS",
            "parameters": {
                "thing": "Teszt Projekt"
            },
            "field_name": name,
            "global": false
        }
    ]
}

Az errors tömb tartalmazza a hibák leírását. Egy konkrét hiba vonatkozhat a kérés valamelyik meghatározott mezejére (ekkor global = false és a field_name kulcs mutat a mezőre, amely a hibát kiváltotta), vagy lehet általános jellegű (ekkor global = true és field_name hiányzik). A code kulcs tartalmazza a tényleges hibakódot. A lehetséges hibakódok listája a kérés típusától függ.

401 Authentication required

A válasz kivételesen egyszerű szöveg (annyi, hogy „Authorization required”).

Érvénytelen felhasználónév vagy jelszó, valamint lejárt token esetén keletkezik ilyen válasz.

403 Permission denied

A válasz JSON, de NEM tartalmazza az általános wrappert.

Akkor keletkezik ilyen válasz, ha az usernév/jelszó vagy token érvényes, de a felhasználónak a kért művelet végrehajtásához nincs jogosultsága.

404 Resource not found

A válasz JSON, de NEM tartalmazza az általános wrappert.

Nem létező endpoint hívásakor keletkezik ilyen válasz. Fontos, hogy a kérés metódusának is stimmelnie kell, tehát ha egy POST-ként definiált endpointot GET-ként hívnak, arra is ilyen hibakód a válasz.

Bejelentkezés

Minden session indításakor kötelező egy session tokent kérni. Ehhez egy valid usernév jelszó párost kell HTTP Basic authentikációval megadni.

A token érvényességi időtartama jelenleg 4 óra, ez minden sikeres kéréssel újraindul. A lejárt tokennel küldött kérések 401-es hibakódú választ generálnak, ilyenkor új tokent kell kérni.

Kérés

/new_session

A Request payload üres.

Válasz

{
    "user_id":31,
    "permissions": [
        "login",
        "change_password",
        ...
    ],
    "session_key":"XXXYYYZZZ",
    "is_support":false,
    "name":"Some User",
    "is_admin":false,
    "username":"somebody"
}

Ebből a session_key kulcs a releváns, a többit csak az admin felület frontendje használja.

Minden további requesthez a a HTTP Basic authentikációt a „_session” felhasználónévvel és az itt megkapott „session_key”-jel kell végrehajtani.

Általános lista-lekérdezés

Az endpointok egy része olyan, hogy valamilyen entitások (például: rekordok, munkaidő-bejegyzések) táblázat-szerű listáját lehet velük lekérni, paraméterezhető oszlopokkal és szűrőkkel. Az ilyen kérések formátuma azonos sémára illeszkedik, csak az engedélyezett oszlopok és szűrők listája függ a konkrét kérés céljától.

Továbbá jellemzően minden ilyen listázó endpointhoz tartozik egy exportáló endpoint, amely (néhány, alább részletezett különbségtől eltekintve) ugyanazt a kérés-formátumot használja. Az a konvenció, hogy ha a listázó endpoint neve /foo/list, amely a választ JSON-ként adja vissza, akkor létezik egy /foo/export is, amely ugyanazt a listát XLS vagy CSV formátumban, fájlként kínálja letöltésre.

Kérés

A payload két tömböt kell tartalmazzon, ezek neve columns és filters. A columns a kért oszlopok (megjelenítendő attribútumok) listáját, a filters pedig az adatokon végrehajtandó szűréseket tartalmazza. Jellemzően minden oszlophoz tartozhat egy szűrő, de az oszlopok és szűrők listájának nem kell megegyeznie (tehát lehetséges olyan kérés, amely az X, Y, Z oszlopkat kéri le, de az A, B, C oszlopok szerint szűr).

A kérés tartalmazhat még egy opcionális kulcsot, amelynek neve limit, értéke egy egész szám. Ha a limit N, akkor a válaszban csak az első N sor fog szerepelni. Az alapértelmezett limit 50.

Alapértelmezésben a válaszban a sorok sorrendje nem definiált, így az sem, hogy mi számit az első N sornak. Ezen úgy lehet segíteni, ha a columns specifikáció valamelyik oszlopánál szerepel egy explicit order kulcs, amelynek értéke asc vagy desc lehet, ekkor a válasz a megjelölt oszlop szerint lesz rendezve, növekvő avagy csökkenő sorrendben.

A columns és filters tömbökben megadható oszlopok típussal rendelkeznek, az oszlop típusa meghatározza, hogy a szűrőfeltételt milyen formátumban kell megadni. A következő típusok fordulnak elő:

„boolean”, „string”, „integer”, „number”, „date”, „datetime”, „time”, „multiselect”, „select”

Egy szűrő aktív, ha meg van adva mellé szűrőfeltétetel, azaz condition kulcs. A szűrőfeltétel formátumai a következők

string szűrőknél a feltétel string típusú, a backend a megadott mintára illeszkedő sorokat adja vissza.
boolean szűrőknél a feltétel true vagy false lehet.
multiselect szűrőknél a feltétel egy számokat (numerikus ID-ket) tartalmazó tömb. Hogy minek az ID-jeire vonatkozik a szűrés, az az oszlop nevétől/céljától függ, és az alább részletezett filterdata mechanizmussal deríthető ki.
select szűrőknél a feltétel egy darab szám (numerikus ID).
a date/time/datetime szűrők egy időtartományt határoznak meg. A szűrőfeltétel egy objektum, amely a type és value kulcsokat tartalmazza. Ha type értéke absolute, akkor a value egy objektum kell legyen, amelyben a from illetve to kulcsok határozzák meg a kívánt időtartomány elejét és végét. Ha a type értéke relative, akkor a value értéke egy string, amely egy relatív időtartományt határoz meg. A lehetséges értékek:
- „today”
- „yesterday”
- „last week”
- „this week”
- „last month”
- „this month”
- „last year”
- „this year”
number/integer szűrőknél további kötelező mezők vannak:
- display_format, értékei lehetnek: time, raw, percentage
- is_range, boolean
- minimum és maximum, a megengedett számtartomány alsó ill. felső határa.
- a szűrőfeltétel egy objektum, amelyben az is_range értékétől függően vagy a value (ha is_range hamis), vagy a from és to kulcsoknak kell szerepelnie (ha is_range igaz).

Példa:

{
   "limit" : 5,
   "columns" : [
      {
         "name" : "project"
      },
      {
         "name" : "hidden"
      }
   ],
   "filters" : [
      {
         "condition" : false,
         "name" : "hidden",
         "type" : "boolean"
      }
   ]
}

Válasz

A válaszban a data tömb tartalmazza a lekérdezés eredményét. A tömb minden eleme egy objektum, amelyben a kulcsok a lekérdezés columns szakaszában megadott oszlopoknak felelnek meg (ezen kívül a legtöbb lekérdezés eredményében minden objektumban szerepel még egy plusz id mező is, amely a lekérdezett entitást egyértelműen azonosítja).

Ezen felül szerepel még a válaszban egy config objektum is, amelyben a have_more boolean mondja meg, hogy a válasz a szűrőfeltételeknek megfelelő összes elérhető sort tartalmazza-e. Ha például a feltételeknek 70 sor felelt volna meg, de a kérésben 50-es limit szerepelt (akár implicit módon), akkor have_more true értéket vesz fel, innen tudható, hogy az eredmény nem teljes, és vagy a szűrőfeltételeket kell módosítani, vagy a limitet növelni az összes sor lekérdezéséhez.

Példa:

{
      "config" : {
         "have_more" : true
      },
      "data" : [
         {
            "hidden" : false,
            "project" : "Teszt Project Chavez exter-marriage",
            "id" : 1
         },
         {
            "id" : 2,
            "hidden" : false,
            "project" : "Teszt Project collar-shaping junk-bottle"
         },
         {
            "hidden" : false,
            "project" : "Teszt Project chondrosarcoma suburbanize",
            "id" : 4
         },
         {
            "id" : 5,
            "project" : "Teszt Project borer NCCL",
            "hidden" : false
         },
         {
            "hidden" : false,
            "project" : "Teszt Project anthography hue",
            "id" : 6
         }
      ]
   }

Export

A /foo/export változat a fentiekhez képest egy plusz kötelező kulcsot tartalmaz, amelynek neve download, és a lehetséges értékei ‘csv’ vagy ‘xls’, amely a letöltendő fájl típusát határozza meg.

A columns és filters tömbök kötelezőek és ugyanazokat az oszlop-specifikációkat kell, hogy tartalmazzák, mint a megfelelő /foo/list kérés. A limit kulcs is használható, azzal a különbséggel, hogy ha hiányzik, akkor az eredmény az összes sort tartalmazni fogja.

A válasz a kért típusú fájlként (CSV vagy XLS) töltődik le.

Filterdata

/search/filterdata

A select és multiselect típusú szűrőfeltételekben használható numerikus azonosítók és a hozzájuk tartozó nevek kérdezhetők le ezzel az endpointtal.

Kérés

A payload objektumban az alább felsorolt kulcsok szerepelhetnek (egy vagy több). Alapesetben a hozzájuk tartozó értékek üres objektumok, de néhány esetben további paramétereket is meg lehet adni, amelyekkel a keresés feltételeit lehet módosítani.

„calldirection”: hívásirányok (kimenő vs. bejövő)
„callreason_types”: hívás végének lehetséges okai
„communication_method”: audio vs. video
„emails”: a rendszer felhasználóinak email-címei
- opcionális paraméterek:
  - all: boolean – ha true: az inaktív felhasználókat is listázza
  - project_id: szám – csak az ehhez a projekthez rendelt felhasználókat listázza
„files”: csatolmányként feltöltött fájlok
„global_roles”: a felhasználók lehetséges jogosultsági szintjei
„operatorstates”: operátori állapotok
„project_roles”: a felhasználók kampányhoz kötött jogosultsági szintjei
„projectdata_column”: adott kampányhoz tartozó rekordokban előforduló oszlopok nevei
- kötelező paraméterek:
  - project_id: ennek a projektnek az oszlopait listázza
„projects”: kampányok nevei
- opcionális paraméterek:
  - all: boolean – ha true, az inaktívakat is listázza
  - type: [outgoing_voice, incoming_voice, incoming_video] – csak az ilyen típusú kampányokat listázza
„queues”: hívási sorok nevei
- opcionális paraméterek:
  - all: boolean
„robinson_lists”: Robinson-listák
- opcionális paraméterek:
  - all: boolean – ha true, az inaktívakat is listázza
„scripts”: adott kampányhoz tartozó scriptek
- kötelező paraméterek:
  - project_id: ennek a projektnek az scriptjeit listázza
- opcionális paraméterek:
  - all: boolean – ha true: az inaktív scripteket is listázza
„termination_categories”: terminációs kategóriák (pl. sikeres vs. sikertelen)
„terminations”: terminációk (lezárások)
- opcionális paraméterek:
  - all: boolean – ha true: az inaktív terminációkat is listázza
  - project_id: szám – csak az ehhez a projekthez rendelt terminációkat listázza
  - termination_category_id: szám – csak az ilyen kategóriába tartozó terminációkat listázza
  - hide_redial: a redial terminációt ne listázza ಠ_ಠ
„usernames”: a rendszer felhasználóinak bejelentkezési nevei
- opcionális paraméterek:
  - all: boolean – ha true: az inaktív felhasználókat is listázza
  - project_id: szám – csak az ehhez a projekthez rendelt felhasználókat listázza
„users”: a rendszer felhasználóinak valódi nevei
- opcionális paraméterek:
  - all: boolean – ha true: az inaktív felhasználókat is listázza
  - project_id: szám – csak az ehhez a projekthez rendelt felhasználókat listázza
„video_projects”: video kampányok nevei

Példa:

{
    "users":{"all":true},
    "projects":{},
    "operatorstates":{},
    "video_projects":{}
}

Válasz

A válasz objektumban a kérésben megadott kulcsok szerepelnek, amelyek mindegyikéhez egy-egy tömb tartozik. A tömbök elemei az egyes entitások azonosítóját és nevét tartalmazó objektumok. Ez utóbbiak mindig tartalmazzák az id és name kulcsokat.

Példa:

{
      "video_projects":[
         {
            "id": 1,
            "name": "demo"
         }
      ]
      "operatorstates" : [
         {
            "id" : 13,
            "name" : "Állapotváltást kér"
         },
         {
            "id" : 3,
            "name" : "Beszélget"
         },
         {
            "id" : 7,
            "name" : "Ebédel"
         },
         {
            "id" : 10,
            "name" : "Előmunka"
         },
         {
            "id" : 15,
            "name" : "Hívási sor váltás"
         },
         {
            "id" : 6,
            "name" : "Kézi hívás"
         },
         {
            "id" : 12,
            "name" : "Ki akar lépni"
         },
         {
            "id" : 16,
            "name" : "My custom state"
         },
         {
            "id" : 17,
            "name" : "My custom state 2"
         },
         {
            "id" : 8,
            "name" : "Oktatáson van"
         },
         {
            "id" : 14,
            "name" : "Operátori beszélgetés"
         },
         {
            "id" : 4,
            "name" : "Regisztrál"
         },
         {
            "id" : 2,
            "name" : "Szünetet tart"
         },
         {
            "id" : 1,
            "name" : "Ügyfélre vár"
         },
         {
            "id" : 5,
            "name" : "Visszahívásra vár"
         }
      ],
      "projects" : [
         {
            "id" : 41,
            "name" : "_______"
         },
         {
            "id" : 23,
            "name" : "bejovo"
         },
         {
            "id" : 42,
            "name" : "dd                f"
         },
         {
            "id" : 40,
            "name" : "Operátor próba"
         },
         {
            "id" : 27,
            "name" : "Kampány másolás"
         },
         {
            "id" : 28,
            "name" : "Kampány másolás 2"
         },
         {
            "id" : 29,
            "name" : "Nottaken"
         },
         {
            "id" : 39,
            "name" : "Szkriptszerkesztés"
         },
         {
            "id" : 37,
            "name" : "Szkriptszerkesztés3"
         },
         {
            "id" : 38,
            "name" : "Szkriptszerkesztés4"
         },
         {
            "id" : 22,
            "name" : "Telesales"
         },
         {
            "id" : 34,
            "name" : "Tranzakció alapú időzített E-mail küldés"
         },
         {
            "id" : 33,
            "name" : "Tranzakció alapú időzített SMS küldés"
         },
         {
            "id" : 25,
            "name" : "Try"
         },
         {
            "id" : 26,
            "name" : "Try2"
         },
         {
            "id" : 1,
            "name" : "Tudásbázis"
         },
         {
            "id" : 35,
            "name" : "Ügyfélszolgálat feladat II. kör"
         },
         {
            "id" : 21,
            "name" : "Ügyfélszolgálat feladat I. kör"
         },
         {
            "id" : 30,
            "name" : "webugyteszt"
         }
      ],
      "users" : [
         {
            "id" : 18,
            "name" : "Admin"
         },
         {
            "id" : 42,
            "name" : "Admin1"
         },
         {
            "id" : 22,
            "name" : "Operátor1"
         },
         {
            "id" : 26,
            "name" : "Operátor11"
         },
         {
            "id" : 40,
            "name" : "Operátor3"
         },
         {
            "id" : 33,
            "name" : "Medialetolto"
         },
         {
            "id" : 44,
            "name" : "Operátor"
         },
         {
            "id" : 21,
            "name" : "Operátor 123"
         },
         {
            "id" : 23,
            "name" : "Operátor 11"
         },
         {
            "id" : 19,
            "name" : "Operátor 12"
         },
         {
            "id" : 24,
            "name" : "Operátor 22"
         },
         {
            "id" : 43,
            "name" : "Operátor 456"
         },
         {
            "id" : 41,
            "name" : "Jó"
         }
      ]
   }

Részletes munkaidő-statisztika

/stat/worklog_detailed/list

Ez az endpoint az operátorok által a webes kliensben eltöltött idő részletes lekérdezésére szolgál.

A szűrőfeltételek, valamint a visszaadott adatok értelmezéséhez a következőket érdemes tudni:

Az operátorok minden pillanatban, amikor a Comnica klienst használják, valamilyen operátori állapotban vannak. Ilyen állapotok például: Beszélget, Ügyfélre vár, Szüneten van. A rendszer eleve definiál néhány, a működéshez szükséges operátori állapotot, de újak is felvehetők az adminisztrátori felületen. Ezen felül az operátor a Comnica kliens használata közben be van jelentkezve egy vagy több hívási sorba, és ezek között menet közben is válthat. A rendszer minden állapotváltozást, továbbá minden hívásisor-váltást regisztrál, vagyis a rendszer használata közben keletkezik egy részletes napló, amely azt tartalmazza, hogy melyik operátor melyik hívási sorokban, milyen állapotban mettől meddig mennyi időt töltött. A részletes munkaidő-statisztika valójában ennek a naplónak a rugalmas lekérdezésére szolgál. Az eredmény sorai ennek a naplónak a bejegyzései, ha úgy tetszik, munkaidő-szeletek. A kívánt oszlopokat és a szűrőfeltételeket az „Általános lista-lekérdezés” szakaszban részletezett módon lehet megadni, és a lehetséges szűrők típusainak jelentése is ott olvasható.

Ennél a statisztikánál van egy szűrőfeltétel, amelyet kötelező megadni, ennek neve interval és a típusa datetime. Ezzel a szűrővel lehet a lekérdezett időtartományt megszorítani (abszolút intervallum is megadható kezdő- és végponttal, illetve relatív hivatkozás, pl. „today”).

A lehetséges további oszlopok ill. szűrők

user_name
- Ha szerepel az oszlopok között, akkor az eredmény minden sora tartalmazni fogja a felhasználó nevét (akihez az adott bejegyzés tartozik).
- Ha szerepel a szűrők között, akkor csak a szűrőfeltételben megadott felhasználók bejegyzései jelennek meg a listában. Multiselect típusú szűrő, vagyis a keresett felhasználók id-jeit (és nem a nevüket) kell megadni egy tömbben a szűrőfeltételben (Lásd „users” filterdata).
description
- Ha szerepel az oszlopok között, akkor az eredmény minden sora tartalmazni fogja az operátori állapot nevét.
- Ha szerepel a szűrők között, akkor csak a szűrőfeltételben megadott operátori állapotok jelennek meg a listában. Multiselect típusú szűrő, vagyis a keresett operátori állapotok id-jeit (és nem a nevüket) kell megadni egy tömbben a szűrőfeltételben (Lásd „operatorstates” filterdata).
counts_as_work
- Ha szerepel az oszlopok között, akkor az eredmény minden sora tartalmazni fogja, hogy bejegyzés munkának számít-e (ez minden operátori állapotnál meg van határozva, hogy munkának számít-e vagy nem).
- Ha szerepel a szűrők között, akkor csak a munkának számító (vagy nem annak számító) bejegyzések jelennek meg. Boolean típusú szűrő, azaz true vagy false lehet a feltétel.
status_begin
- Ha szerepel az oszlopok között, akkor az eredmény minden sora tartalmazni fogja az bejegyzés kezdetét.
- Ehhez az oszlophoz nem tartozik szűrőfeltétel (azonban lásd az interval szűrőt).
status_end
- Ha szerepel az oszlopok között, akkor az eredmény minden sora tartalmazni fogja az bejegyzés végét.
- Ehhez az oszlophoz nem tartozik szűrőfeltétel (azonban lásd az interval szűrőt).
duration
- Ha szerepel az oszlopok között, akkor az eredmény minden sora tartalmazni fogja az bejegyzés időtartamát (azaz, hogy a felhasználó mennyi időt töltött a kérdéses állapotban).
- Ha szerepel a szűrők között, akkor csak a megadott időtartam-tartományba eső bejegyzések jelennek meg az eredményben. Number típusú szűrő, azaz a minimum és maximum kulcsokkal kell megadni a kívánt számtartományt, percben (hogy mekkoránál hosszabb és mekkoránál rövidebb időtartamú bejegyzések jelenjenek meg.)
project_name
- Ha szerepel az oszlopok között, akkor az eredmény minden sora tartalmazni fogja azt, hogy a felhasználó az adott bejegyzésben melyik kampányokba volt bejelentkezve.
- Ha szerepel a szűrők között, akkor csak a szűrőfeltételben megadott kampányokhoz tartozó bejegyzések jelennek meg a listában. Multiselect típusú szűrő, vagyis a keresett kampányok id-jeit (és nem a nevüket) kell megadni egy tömbben a szűrőfeltételben (Lásd „projects” filterdata).
queue_name
- Ha szerepel az oszlopok között, akkor az eredmény minden sora tartalmazni fogja azt, hogy a felhasználó az adott bejegyzésben melyik hívási sorokba volt bejelentkezve.
- Ha szerepel a szűrők között, akkor csak a szűrőfeltételben megadott hívási sorokhoz tartozó bejegyzések jelennek meg a listában. Multiselect típusú szűrő, vagyis a keresett hívási sorok id-jeit (és nem a nevüket) kell megadni egy tömbben a szűrőfeltételben (Lásd „queues” filterdata).

Kérés

Az alábbi példa az összes lehetséges oszlopot, valamint a szűrők típusát és az elvárt szűrőfeltételeket mutatja. Nem muszáj minden oszlopot ill. szűrőt megadni, és nem szükséges, hogy ugyanazokat a szűrőket és oszlopokat adjuk meg (a valóságban ennél a statisztikánál célszerű minden oszlopot megadni a teljes eredményhez).

{
      "columns" : [
         {
            "name" : "user_name"
         },
         {
            "name" : "description"
         },
         {
            "name" : "counts_as_work"
         },
         {
            "name" : "status_begin"
         },
         {
            "name" : "status_end"
         },
         {
            "name" : "duration"
         },
         {
            "name" : "project_name"
         },
         {
            "name" : "queue_name"
         }
      ],
      "filters" : [
         {
            "condition" : [
               17,
               22,
               25,
               44,
               35,
               37
            ],
            "name" : "user_name",
            "type" : "multiselect"
         },
         {
            "condition" : [
               13,
               3,
               7,
               10
            ],
            "name" : "description",
            "type" : "multiselect"
         },
         {
            "condition" : true,
            "name" : "counts_as_work",
            "type" : "boolean"
         },
         {
            "condition" : {
               "type" : "relative",
               "value" : "this week"
            },
            "name" : "interval",
            "type" : "datetime"
         },
         {
            "condition" : {
               "from" : 0,
               "to" : 3706
            },
            "display_format" : "time",
            "is_range" : true,
            "maximum" : 7200,
            "minimum" : 0,
            "name" : "duration",
            "type" : "integer"
         },
         {
            "condition" : [
               35,
               21,
               22
            ],
            "name" : "project_name",
            "type" : "multiselect"
         }
      ],
      "limit" : 50
   }

Válasz

{
      "config" : {
         "have_more" : false
      },
      "data" : [
         {
            "counts_as_work" : true,
            "description" : "Állapotváltást kér",
            "duration" : 1.02511,
            "id" : 2656,
            "project_name" : "Ügyfélszolgálat feladat II. kör",
            "queue_name" : "Ügyfélszolgálat feladat II. kör",
            "status_begin" : "2019-10-14 11:32:11.88445+02",
            "status_end" : "2019-10-14 11:32:12.90956+02",
            "user_name" : "Kovács Géza"
         },
         {
            "counts_as_work" : true,
            "description" : "Állapotváltást kér",
            "duration" : 1.02598,
            "id" : 2659,
            "project_name" : "Ügyfélszolgálat feladat II. kör",
            "queue_name" : "Ügyfélszolgálat feladat II. kör",
            "status_begin" : "2019-10-14 13:04:12.85681+02",
            "status_end" : "2019-10-14 13:04:13.88279+02",
            "user_name" : "Kovács Géza"
         },
         {
            "counts_as_work" : true,
            "description" : "Előmunka",
            "duration" : 1.69876,
            "id" : 2661,
            "project_name" : "Ügyfélszolgálat feladat II. kör",
            "queue_name" : "Ügyfélszolgálat feladat II. kör",
            "status_begin" : "2019-10-14 13:04:22.81521+02",
            "status_end" : "2019-10-14 13:04:24.51397+02",
            "user_name" : "Kovács Géza"
         },
         {
            "counts_as_work" : true,
            "description" : "Állapotváltást kér",
            "duration" : 1.01377,
            "id" : 2662,
            "project_name" : "Ügyfélszolgálat feladat II. kör",
            "queue_name" : "Ügyfélszolgálat feladat II. kör",
            "status_begin" : "2019-10-14 13:04:24.51397+02",
            "status_end" : "2019-10-14 13:04:25.52774+02",
            "user_name" : "Kovács Géza"
         },
         {
            "counts_as_work" : true,
            "description" : "Beszélget",
            "duration" : 3.58388,
            "id" : 2664,
            "project_name" : "Ügyfélszolgálat feladat II. kör",
            "queue_name" : "Ügyfélszolgálat feladat II. kör",
            "status_begin" : "2019-10-14 13:04:32.13318+02",
            "status_end" : "2019-10-14 13:04:35.71706+02",
            "user_name" : "Kovács Géza"
         },
         {
            "counts_as_work" : true,
            "description" : "Állapotváltást kér",
            "duration" : 1.01884,
            "id" : 2674,
            "project_name" : "Telesales, Ügyfélszolgálat feladat II. kör, Ügyfélszolgálat feladat I. kör",
            "queue_name" : "Telesales, Ügyfélszolgálat feladat II. kör, Ügyfélszolgálat feladat I. kör",
            "status_begin" : "2019-10-14 14:18:30.85001+02",
            "status_end" : "2019-10-14 14:18:31.86885+02",
            "user_name" : "Nagy Napóleon"
         },
         {
            "counts_as_work" : true,
            "description" : "Állapotváltást kér",
            "duration" : 1.01853,
            "id" : 2678,
            "project_name" : "Telesales, Ügyfélszolgálat feladat II. kör, Ügyfélszolgálat feladat I. kör",
            "queue_name" : "Telesales, Ügyfélszolgálat feladat II. kör, Ügyfélszolgálat feladat I. kör",
            "status_begin" : "2019-10-14 14:29:30.96704+02",
            "status_end" : "2019-10-14 14:29:31.98557+02",
            "user_name" : "Nagy Napóleon"
         },
         {
            "counts_as_work" : true,
            "description" : "Előmunka",
            "duration" : 656.19123,
            "id" : 2680,
            "project_name" : "Ügyfélszolgálat feladat II. kör",
            "queue_name" : "Ügyfélszolgálat feladat II. kör",
            "status_begin" : "2019-10-14 14:29:32.79901+02",
            "status_end" : "2019-10-14 14:40:28.99024+02",
            "user_name" : "Nagy Napóleon"
         },
         {
            "counts_as_work" : true,
            "description" : "Állapotváltást kér",
            "duration" : 2.01933,
            "id" : 2681,
            "project_name" : "Telesales, Ügyfélszolgálat feladat II. kör, Ügyfélszolgálat feladat I. kör",
            "queue_name" : "Telesales, Ügyfélszolgálat feladat II. kör, Ügyfélszolgálat feladat I. kör",
            "status_begin" : "2019-10-14 14:40:28.99024+02",
            "status_end" : "2019-10-14 14:40:31.00957+02",
            "user_name" : "Nagy Napóleon"
         },
         {
            "counts_as_work" : true,
            "description" : "Állapotváltást kér",
            "duration" : 0.01216,
            "id" : 2683,
            "project_name" : "Telesales, Ügyfélszolgálat feladat II. kör, Ügyfélszolgálat feladat I. kör",
            "queue_name" : "Telesales, Ügyfélszolgálat feladat II. kör, Ügyfélszolgálat feladat I. kör",
            "status_begin" : "2019-10-14 14:40:35.98446+02",
            "status_end" : "2019-10-14 14:40:35.99662+02",
            "user_name" : "Nagy Napóleon"
         }
      ]
   }

Munkaidő-statisztika operátoronként

/stat/worklog_by_users/list

Ez az endpoint a rendszerben töltött időket operátorok szerint csoportosítva adja vissza.

Kérés

Ez a lekérdezés abból a szempontból speciális, hogy a kötött, előre definiált oszlopokon kívül, amelyekhez szűrő is tartozik, az egyes operátori állapotok nevei is szerepelhetnek az oszloplistában (ezekhez azonban nem tartozik szűrő). Az előre definiált oszlopok:

user: felhasználó neve
sum_all: a felhasználó által a kért időtartományon belül az összes rendszerben töltött idő
sum_counts_as_work: a felhasználó által a kért időtartományon belül az összes munkának számító idő

Ezenkívül a lekérdezés filters tömbjében szerepelnie kell egy időtartam-szűrőnek, interval néven.

{
   "columns" : [                          /* a lekért oszlopok */
      {
         "name" : "user",
         "order" : "asc"                 /* növekvő sorrend ezen oszlopok alapján */
      },
      {
         "name" : "sum_all"
      },
      {
         "name" : "sum_counts_as_work"
      },
      {
         "name" : "Ügyfélre vár"
      },
      {
         "name" : "Beszélget"
      },
      {
         "name" : "Regisztrál"
      },
      {
         "name" : "Visszahívásra vár"
      },
      {
         "name" : "Kézi hívás"
      },
      {
         "name" : "Előmunka"
      },
      {
         "name" : "Ki akar lépni"
      },
      {
         "name" : "Állapotváltást kér"
      },
      {
         "name" : "Operátori beszélgetés"
      },
      {
         "name" : "Hívási sor váltás"
      },
      {
         "name" : "Szünetet tart"
      },
      {
         "name" : "Ebédel"
      },
      {
         "name" : "Oktatáson van"
      }
   ],
   "filters" : [
      {
         "condition" : {
            "type" : "relative",
            "value" : "last month"
         },
         "name" : "interval",
         "type" : "datetime"
      }
   ],
   "limit" : 50          
}

Válasz

Az összes számérték (adott állapotban eltöltött idő) másodpercben értendő.

{
   "config" : {
      "have_more" : false
   },
   "data" : [
      {
         "Beszélget" : 926,
         "Ebédel" : 0,
         "Előmunka" : 15985,
         "Hívási sor váltás" : 0,
         "Ki akar lépni" : 4,
         "Kézi hívás" : 59,
         "Oktatáson van" : 0,
         "Operátori beszélgetés" : 0,
         "Regisztrál" : 430,
         "Szünetet tart" : 5702,
         "Visszahívásra vár" : 0,
         "id" : "21",
         "sum_all" : 23232,
         "sum_counts_as_work" : 17530,
         "user" : "XXX YYY",
         "Állapotváltást kér" : 92,
         "Ügyfélre vár" : 34
      },
      {
         "Beszélget" : 1215,
         "Ebédel" : 0,
         "Előmunka" : 53411,
         "Hívási sor váltás" : 0,
         "Ki akar lépni" : 32,
         "Kézi hívás" : 92,
         "Oktatáson van" : 0,
         "Operátori beszélgetés" : 0,
         "Regisztrál" : 1101,
         "Szünetet tart" : 24571,
         "Visszahívásra vár" : 0,
         "id" : "sum",
         "sum_all" : 80987,
         "sum_counts_as_work" : 56416,
         "user" : "∑",
         "Állapotváltást kér" : 234,
         "Ügyfélre vár" : 331
      }
   ]
}

Integráció külső rendszerekkel

Többször felmerült az igény a Calgo/Comnica CC élete során, hogy az ügyfél szeretné a saját szoftverével összekötni a Comnica rendszert. Erre hoztuk létre az integrációs endpointokat, amiknél az a kritérium, hogy az adatokat minél felhasználható, utómunkát minél kevésbé igénylő formában, és lehetőleg egyszerű interakció hatására adjuk vissza.

Integrációs endpointok:

CC rekord letöltése

Path: /integration/cc/record/load/v1

Request payload:

{ "id": 42 }

Az egyetlen mező az id, a rekord egyedi azonosítója.

Response payload:

CC record load response

{
    "comments": [
        {
            "comment": "Example comment 1",
            "created_at": "2019-11-19 16:21:17+01",
            "id": 13,
            "user_id": 0
        },
        {
            "comment": "Example comment 2",
            "created_at": "2019-11-19 16:22:57+01",
            "id": 14,
            "user_id": 0
        }
    ],
    "contacts": [
        {
            "active": true,
            "contact": "3611234567",
            "id": 141,
            "name": "",
            "priority": 1,
            "type": "phone"
        },
        {
            "active": true,
            "contact": "3619876543",
            "id": 142,
            "name": "",
            "priority": 2,
            "type": "phone"
        }
    ],
    "custom_data": {
        "aaa": "äää",
        "bbb": "ßßß",
        "phone": "3611234567"
    },
    "system_columns": {
        "callback_to_user_id": null,
        "dial_from": null,
        "dial_to": null,
        "id": 72,
        "is_redial": false,
        "manual_redial": false,
        "next_call": null,
        "priority": 1,
        "project_id": 9,
        "termination_id": null,
        "tries_since_last_contact": null
    }
}

Részletek:

comments: a rekord kommentjei tömbben; tartalom, időpont, id, user_id mezőkkel
contacts: a rekordhoz tartozó kontaktok tömbben; active, telefonszám, id, kontakt neve, prioritás, típus
custom_data: a rekordhoz tartozó szkriptmezők
system_columns: a rekord rendszermezői; visszahívás usere, hívhatóság tól-ig, id, visszahívás-e, kézi beállítású visszahívás-e, következő hívás időpontja, prioritás, project_id, terminációs kód, utolsó sikeres kapcsolatfelvétel óta próbálkozások száma

CC rekord létrehozása

Path: /integration/cc/record/save/v1

Request payload:

{
    "comments": [
        {
            "comment": "Example comment 1",
            "created_at": "2019-11-19 16:21:17+01"
        },
        {
            "comment": "Example comment 2",
            "created_at": "2019-11-19 16:22:57+01"
        }
    ],
    "contacts": [
        {
            "active": true,
            "contact": "3611234567",
            "name": "",
            "preferred": true,
            "priority": 1,
            "source_column": "phone",
            "type": "phone"
        },
        {
            "active": true,
            "contact": "3619876543",
            "name": "",
            "preferred": false,
            "priority": 2,
            "source_column": "phone2",
            "type": "phone"
        }
    ],
    "custom_data": {
        "aaa": "äää",
        "bbb": "ßßß",
        "phone": "3611234567"
    },
    "system_columns": {
        "callback_to_user_id": null,
        "dial_from": null,
        "dial_to": null,
        "manual_redial": null,
        "next_call": null,
        "priority": 1,
        "project_id": 9
    }
}

Részletek:

comments: a rekord kommentjei tömbben; tartalom, időpont
contacts: a rekordhoz tartozó kontaktok tömbben; active, telefonszám, kontakt neve, preferált-e (ebből lesz a rekordba bejegyezve a preferred_contact_id, ami alapján a hívást intézzük), prioritás (1 es 9 kozott, a 9 a magasabb!), forrásoszlop (ezt a kliens megjeleníti az operátornak, hogy tudja, hogy miféle telefonszám az – otthoni, munkahelyi –, például), kontakt típusa (általában phone vagyis telefonszám, de a jövőben lehet ez más is)
custom_data: a rekordhoz tartozó adatmezők. A choice típusú mezők értékei mindig tömbként adandók meg, akkor is, ha csak egy értéke van: ["savoury"], ["red"] (lásd később az adatmezők lekérdezése részt)
system_columns: a rekord rendszermezői; visszahívás usere, hívhatóság tól-ig, kézi beállítású visszahívás-e, következő hívás időpontja, prioritás, project_id (ez az egyetlen kötelező mező)

A bevitt adatokon típusellenőrzéseket végzünk. A rekordok adatmezőinek a típusát a CC projekt adatmezőinek lekérdezése szakaszban leírtak szerint lehet lekérdezni.

Response payload:

{ "id": 42 }

CC rekord szerkesztése

Path: /integration/cc/record/update/v1

Request payload:

{
    "id": 42,
    "custom_data": {
        "aaa": "äää",
        "bbb": "ßßß",
        "phone": "3611234567"
    },
    "system_columns": {
        "callback_to_user_id": null,
        "manual_redial": null,
        "next_call": null,
        "termination_id": 9
    }
}

Részletek:

id: a rekord azonosítója
custom_data: a rekordhoz tartozó adatmezők. A choice típusú mezők értékei mindig tömbként adandók meg, akkor is, ha csak egy értéke van: ["savoury"], ["red"] (lásd később az adatmezők lekérdezése részt)
system_columns: a rekord rendszermezői; visszahívás usere, kézi beállítású visszahívás-e, következő hívás időpontja, termináció id (ez a terminations filterdata adott project_id-ra szűkített lekérdezésével tudható meg, lásd a Filterdata szakaszt)

A bevitt adatokon típusellenőrzéseket végzünk. A rekordok adatmezőinek a típusát a CC projekt adatmezőinek lekérdezése szakaszban leírtak szerint lehet lekérdezni.

Response payload:

{ "id": 42 }

CC projekt adatmezőinek lekérdezése

Path: /integration/cc/project/fields/list/v1

Request payload:

{ "project_id": 9 }

Response payload:

[
   {
      "datatype" : "phone",
      "name" : "phone",
      "type" : "input",
      "is_contact" : true,
      "id" : 153
   },
   {
      "type" : "input",
      "is_contact" : true,
      "id" : 154,
      "datatype" : "phone",
      "name" : "phone2"
   },
   {
      "is_contact" : false,
      "type" : "input",
      "id" : 155,
      "datatype" : "string",
      "name" : "aaa"
   },
   {
      "name" : "bbb",
      "datatype" : "string",
      "id" : 156,
      "type" : "input",
      "is_contact" : false
   },
   {
      "datatype" : "number",
      "name" : "num",
      "type" : "input",
      "is_contact" : false,
      "id" : 157
   },
   {
      "is_contact" : false,
      "type" : "input",
      "id" : 158,
      "datatype" : "date",
      "name" : "birthday"
   },
   {
      "datatype" : "datetime",
      "name" : "appointment",
      "type" : "input",
      "is_contact" : false,
      "id" : 159
   },
   {
      "selection" : "single",
      "is_contact" : false,
      "name" : "flavour",
      "datatype" : "string",
      "content" : [
         {
            "savoury" : "Savoury"
         },
         {
            "sweet" : "Sweet"
         }
      ],
      "id" : 160,
      "type" : "choice"
   },
   {
      "type" : "choice",
      "id" : 161,
      "content" : [
         {
            "black" : "Black"
         },
         {
            "white" : "White"
         },
         {
            "red" : "Red"
         },
         {
            "grue" : "Grue"
         },
         {
            "yellow" : "Yellow"
         }
      ],
      "datatype" : "string",
      "name" : "colour",
      "is_contact" : false,
      "selection" : "multi"
   }
]

Részletek:

Az előzőekhez képest (amikor csak phone, phone2, aaa, bbb mezők voltak) kiegészítettük pár extra oszloppal a rekordot a példa kedvéért. A következő oszlopok lettek felvéve:
- num nevű oszlop, amibe szám kell kerüljön;
- birthday oszlop amibe dátum (YYYY-MM-DD);
- appointment, amibe időpont (YYYY-MM-DD HH24:MI:SS[.UUUUUU][ZZZZ] — vagyis a törtmásodpercek és az időzóna opcionális, de előfordulhat; az óra 24 órás formában elfogadott);
- flavour, ami egy lista ahol egy konkrét értéket kell kiválasztani egy véges készletből (pl. a szkripten „egyválasztós választó” néven hozható ilyen létre);
- colour, ami egy többértékes lista („többválasztós választó”);

Duplikáció szűrés

Endpoint: api/integration/cc/record/save/v1 (rekord betöltés)

Változás:

ha valtozatlanul hivjuk az endpointot, akkor nincs duplikacio szures
ha a payload-ba az kovetkezo key:value parosok kerulnek, akkor normal duplikacioszures tortenik:
```
"options": { "check_duplicates": "basic" }
```

ha a payload-ba az kovetkezo key:value parosok kerulnek, akkor szigoru duplikacioszures tortenik:
```
"options": { "check_duplicates": "strict" }
```

CC hívásrekordok lekérdezése

Path: /integration/cc/calls/list/v1

Request payload:

{
    "rq_sent": "2020-09-01 00:00:00+00",
    "payload": {
        "columns": [
            { "name": "soundfile_exists" },
            { "name": "call_id" },
            { "name": "record_id" },
            { "name": "calldirection" },
            { "name": "project_name" },
            { "name": "operator_name" },
            { "name": "phone" },
            { "name": "terminated" },
            { "name": "terminating_code" },
            { "name": "termination_category" },
            { "name": "started_at" },
            { "name": "queued_at" },
            { "name": "linked_at" },
            { "name": "hangup_at" },
            { "name": "queue_length" },
            { "name": "hold_length" },
            { "name": "talk_length_without_hold" },
            { "name": "talk_length" },
            { "name": "hangup_reason_type" },
            { "name": "operator_name_not_empty" },
            { "name": "comments" },
            { "name": "ivr_custom_field_1" },
            { "name": "ivr_custom_field_2" },
            { "name": "ivr_custom_field_3" },
            { "name": "ivr_custom_field_4" },
            { "name": "ivr_custom_field_5" },
            { "name": "incomingnumber" }
        ],
        "filters": [
            {
                "name": "call_id",
                "type": "string"
            },
            {
                "name": "record_id",
                "type": "string"
            },
            {
                "name": "project_name",
                "type": "multiselect",
                "items": "projects"
            },
            {
                "name": "operator_name",
                "type": "multiselect",
                "items": "users"
            },
            {
                "name": "phone",
                "type": "string"
            },
            {
                "name": "terminated",
                "type": "boolean"
            },
            {
                "name": "terminating_code",
                "type": "multiselect",
                "items": "terminations"
            },
            {
                "name": "started_at",
                "type": "datetime",
                "required": true,
                "condition": {
                    "type": "relative",
                    "value": "this week"
                }
            },
            {
                "name": "queued_at",
                "type": "datetime"
            },
            {
                "name": "linked_at",
                "type": "datetime"
            },
            {
                "name": "hangup_at",
                "type": "datetime"
            },
            {
                "name": "queue_length",
                "type": "integer",
                "display_format": "time"
            },
            {
                "name": "hold_length",
                "type": "integer"
            },
            {
                "name": "talk_length_without_hold",
                "type": "integer"
            },
            {
                "name": "talk_length",
                "type": "integer"
            },
            {
                "name": "listened",
                "type": "boolean"
            },
            {
                "name": "rating",
                "type": "multiselect",
                "items": "ratings"
            },
            {
                "name": "listened_by",
                "type": "multiselect",
                "items": "users"
            },
            {
                "name": "listened_at",
                "type": "datetime"
            },
            {
                "name": "rated_by",
                "type": "multiselect",
                "items": "users"
            },
            {
                "name": "rated_at",
                "type": "datetime"
            },
            {
                "name": "termination_category",
                "type": "multiselect",
                "items": "termination_categories"
            },
            {
                "name": "soundfile_exists",
                "type": "boolean"
            },
            {
                "name": "hangup_by",
                "type": "multiselect",
                "items": "hangup_by"
            },
            {
                "name": "calldirection",
                "type": "multiselect"
            },
            {
                "name": "hangup_reason_type",
                "type": "multiselect",
                "items": "callreason_types"
            },
            {
                "name": "calltype",
                "type": "string"
            },
            {
                "name": "operator_name_not_empty",
                "type": "boolean"
            },
            {
                "name": "comments",
                "type": "string"
            },
            {
                "name": "ivr_custom_field_1",
                "type": "string"
            },
            {
                "name": "ivr_custom_field_2",
                "type": "string"
            },
            {
                "name": "ivr_custom_field_3",
                "type": "string"
            },
            {
                "name": "ivr_custom_field_4",
                "type": "string"
            },
            {
                "name": "ivr_custom_field_5",
                "type": "string"
            },
            {
                "name": "incomingnumber",
                "type": "multiselect",
                "items": "incomingnumbers"
            }
        ],
        "limit": 50
    }
}

Részletek:

soundfile_exists: létezik hangfájl.
call_id: hívás azonosítója
record_id: ügyfélrekord azonosítója, amellyel kapscolatban létrejött a hívás.
calldirection: hívás irány (bejövő / kimenő)
project_name: melyik kampányban található az ügyfélrekord. Szűrőknél a kampányok azonosítóját tartalmazó tömb.
operator_name: hívást kezelő operátor neve. Szűrőknél az operátorok azonosítóját tartalmazó tömb.
phone: az ügyfél telefonszáma
terminated: lezárt-e az ügyfélrekord
terminating_code: terminációs kód, amivel lezárták a beszélgetést.
termination_category: terminációs kód kategóriája.
started_at: hívás indítás időpontja.
queued_at: hívás hívási sorba kerülésének időpontja (ekkor kezdett el várakozni az operátorra)
linked_at: hívás operátorhoz kapcsolásának időpontja.
hangup_at: hívás megszakítás időpontja.
queue_length: operátorra várakozás hossza (sec)
hold_length: hívástartás hossza (sec)
talk_length_without_hold: beszélgetés hossza hívástartás nélkül.
talk_length: beszélgetés hossza
hangup_reason_type: hívás megszakításának oka
operator_name_not_empty: operátorhoz kapcsolódott a hívás
comments: megjegyzések a híváshoz tartozó ügyfélrekordnál.
ivr_custom_field_{1..5}: egyeztetés alapján IVR-on keresztül kitöltött mezők
incomingnumber: telefonszám, amit bejövő hívás esetén tárcsázott az ügyfél.

Response payload:

{
    "payload": {
        "data": [
            {
                "listened": false,
                "project_name": "teszt1",
                "record_id": "46844",
                "talk_length_without_hold": 13.84735,
                "call_id": "8765",
                "id": 8765,
                "operator_name": "Tesz Elek",
                "project_id": 838,
                "soundfile_exists": true,
                "phone": "3612550567",
                "terminating_code": "bye",
                "talk_length": 13.84735,
                "started_at": "2020-08-18 08:48:06.88883+02",
                "rating": 0,
                "terminated": true
            },
            {
                "terminating_code": "bye",
                "talk_length": 3.2809,
                "started_at": "2020-07-27 14:18:47.91042+02",
                "rating": 0,
                "terminated": true,
                "record_id": "46679",
                "project_name": "teszt1",
                "listened": false,
                "talk_length_without_hold": 3.2809,
                "operator_name": "Tesz Elek",
                "call_id": "8764",
                "id": 8764,
                "soundfile_exists": true,
                "project_id": 684,
                "phone": "3612550567"
            },
            {
                "record_id": "46669",
                "project_name": "teszt2",
                "listened": false,
                "id": 8763,
                "call_id": "8763",
                "operator_name": "Tesz Elek",
                "project_id": 683,
                "soundfile_exists": true,
                "talk_length_without_hold": 3.4847,
                "phone": "3612550567",
                "terminating_code": "bye",
                "started_at": "2020-07-27 14:17:17.94854+02",
                "talk_length": 3.4847,
                "rating": 0,
                "terminated": true
            },
            {
                "talk_length_without_hold": 4.09818,
                "id": 8762,
                "call_id": "8762",
                "operator_name": "Tesz Elek",
                "soundfile_exists": true,
                "project_id": 681,
                "phone": "3612550567",
                "project_name": "teszt2",
                "listened": false,
                "record_id": "46649",
                "rating": 0,
                "terminated": true,
                "terminating_code": "bye",
                "talk_length": 4.09818,
                "started_at": "2020-07-27 14:13:22.91056+02"
            }
        ],
        "config": {
            "have_more": false
        }
    },
    "res_sent": "2020-10-06 11:04:20.775860+0000",
    "rq_rcvd": "2020-10-06 11:04:20.729428+0000"
}

CC rekordok lekérdezése

Path: /integration/cc/record/list/v1

Request payload:

{
    "payload": {
        "columns": [
            {"name": "record_id"},
            {"name": "upload", "order": "desc"},
            {"name": "terminated"},
            {"name": "terminating_code"},
            {"name": "phone"},
            {"name": "phone_comment"}
        ],
        "filters": [
            {"condition": 280, "name": "project", "type": "select"},
            {
                "condition": {
                    "type": "absolute",
                    "value": {
                        "from": "2019-11-25 00:00:00+00",
                        "to": "2019-12-01 23:59:59+00"
                    }
                },
                "name": "upload",
                "type": "datetime"
            }
        ],
        "limit": 50
    },
    "rq_sent": "2022-05-31 16:04:57.879+0000"
}

Filterek:

project: type=select, kötelező — a project id-je.
record_id: type=string
upload: type=datetime — feltöltés időpontja
terminated: type=boolean — terminált-e?
terminating_code: type=multiselect, filterdata=terminations — terminációs kód
termination_category: type=multiselect, filterdata=termination_categories — terminációs kategória
next_call: type=datetime — következő (vissza)hívás ideje
callback_to_user: type=multiselect, filterdata=users — szűrés visszahíváshoz rendelt user alapján
is_redial: type=boolean — visszahívás-e?
manual_redial: type=boolean — kézi, explicite beállított visszahívás-e, vagy automatikus újrapróbálkozás
last_comment: type=string — utolsó komment
last_agent_work_at: type=datetime — utolsó operátori munka ideje
updated_at: type=datetime — utolsó módosítás ideje
inserted_at: type=datetime — a rekord rendszerbe kerülésének ideje
last_agent: type=multiselect, filterdata=users — a rekorddal utoljára dolgozó operátor
last_call_at: type=datetime — az utolsó hívás időpontja
valamint a projektmező listázóval begyűjthető adatmezők amiket az adatbázis feltöltésekor vagy a szkript kitöltésekor töltünk fel adattal

Response payload:

{
    "payload": {
        "config": {
            "have_more": false
        },
        "data": [
            {
                "phone": "3655555123",
                "id": 14396,
                "upload": "2019-11-27 10:57:17.801476+00",
                "terminated": true,
                "phone_comment": "",
                "record_id": 14396,
                "terminating_code": "bye"
            },
            {
                "upload": "2019-11-27 10:57:17.801476+00",
                "phone": "3655555987",
                "id": 14397,
                "record_id": 14397,
                "terminated": false,
                "phone_comment": ""
            },
            ...
        ]
    },
    "rq_rcvd": "2022-05-31 18:04:58.128130+0200",
    "res_sent": "2022-05-31 18:04:58.386605+0200"
}

CC tömeges művelet rekordokon (bulk)

Path: /integration/cc/record/bulk_modify/v1

Method: POST

A request alapvetően olyan, mint a fenti Rekordok listázása listrequest, pár extra paraméterrel. A filterekkel beállítjuk hogy milyen tulajdonságú rekordokkal szeretnénk dolgozni, majd az action, subaction és params paraméterekkel felkonfiguráljuk a bulk műveletet. Példa a fenti lista alapján: vesszük az összes 356-os kódú terminált rekordot, és áttermináljuk őket 458-as terminációs kódra.

{
    "payload": {
        "action": "change_termination",
        "filters": [
            {
                "condition": 280,
                "name": "project",
                "type": "select"
            },
            {
                "condition": {
                    "type": "absolute",
                    "value": {
                        "from": "2019-11-25 00:00:00+00:00",
                        "to": "2019-12-01 23:59:59+00:00"
                    }
                },
                "name": "upload",
                "type": "datetime"
            },
            {
                "condition": [
                    356
                ],
                "name": "terminating_code",
                "type": "multiselect"
            }
        ],
        "params": {
            "condition": 458
        }
    },
    "rq_sent": "2022-05-31 16:53:55.841+0000"
}

Request mezők a listrequest paramétereken felül:

action: a művelet, lehetséges értékei „change_termination”, „change_callback”, „change_data”
subaction: néha a műveletnek vannak alváltozatai.
- change_callback action esetén: „change_to_manual_callback”, „change_to_auto_callback”, „change_callback_user”, „remove_callback”
params: a művelet és az alművelet által igényelt egyéb argumentumok, mint a terminációs kód vagy az átírandó mező neve és új értéke
dry_run: nem végzi el a műveletet, csak visszatér a talált rekordok számával

Válasz:

{
    "payload": {
        "count": 11
    },
    "res_sent": "2022-05-31 18:53:56.438751+0200",
    "rq_rcvd": "2022-05-31 18:53:56.037511+0200"
}

Termináció átállítása (action: change_termination)

A params rész tartalma egyetlen „condition” kulcsú érték, a kívánt értéknek megfelelően.

Mezőérték átírása (action: change_data)

A params rész tartalma a mezőnév és az érték:

{
   ...
   "params": {
      "field": "szuletesi_hely",
      "value": "Budapest"
   }
}

Visszahívás átállítása (action: change_callback)

A payload a subactionoktól függően változik

change_to_manual_callback: Userhez rendelt visszahívás beállítása; szükséges paraméterek a user_id és next_call (a hívás időpontja)
change_to_auto_callback: Kicsit hibás elnevezés, ez közös listás visszahívást állít be, tehát nincs user_id-hez rendelve; szükséges paraméter a next_call
change_callback_user: Minden marad, de a rekordok kezelését más usernek adjuk; szükséges paraméter a user_id
remove_callback: Visszahívás megszüntetése; nincs extra paraméter

CC hangfájl letöltése

Path: /recording/<callid>/download

Method: GET

Auth: basic

Az adott callid-hoz tartozó hangfájlt tölti le.

Video rekord létrehozása

Path: /video/projectdata/create

Request payload:

{
    "rq_sent": "2020-09-01 00:00:00+00",
    "payload": {
        "video_project_id": 1,
        "data": {
            "identifying_company": "Comnica",
            "name": "Teszt Elke",
            "birth_name": "Tesztelő Elke",
            "birth_place": "Csömör",
            "birth_date": "2000-01-01",
            "mothers_maiden_name": "Kulcsos Katalin",
            "permanent_zip": "1119",
            "permanent_country": "Magyarország",
            "permanent_city": "Budapest",
            "permanent_street": "Mohai út 38.",
            "temporary_zip": "1119",
            "temporary_country": "Magyarország",
            "temporary_city": "Budapest",
            "temporary_street": "Mohai út 38.",
            "email": "support@comnica.cc",
            "phone": "3612550991",
            "simplified_identification": true
        }
    }
}

Részletek:

video_project_id: a video kampány azonosítója (lásd. Filterdata fejezet)
data: a rekordban tárolni kívánt adatok
- kulcsok: oszlopnevek
- értékek: az oszlopban tárolni kívánt értékek

A példában megadott oszlopok kötelező elemek. Hiányuk vagy érték nélküli megadásuk sikertelen betöltést eredményez.

További – a data-ban nem szerplő oszlopok – is megadhatóak, amennyiben léteznek. A rekordok adatmezőinek a típusát a Video projekt adatmezőinek lekérdezése szakaszban leírtak szerint lehet lekérdezni.

Response payload:

{
  "payload": {
    "url": "video url, amin kersztül az ügyfél be tud lépni a rendszerbe",
    "video_projectdata_id": 42
  },
  "res_sent": "2020-01-01 00:00:00+00",
  "rq_rcvd": "2020-01-01 00:00:00+00"
}

Video projekt adatmezőinek lekérdezése

Path: /video/project/column/list

Request payload:

{
    "rq_sent": "2020-09-01 00:00:00+00",
    "payload": {
        "project_id": 1
    }
}

Response payload:

{
  "rq_rcvd": "2020-09-22 16:47:15.706141+0200",
  "res_sent": "2020-09-22 16:47:15.821405+0200",
  "payload": [
    {
      "mandatory_at_output": true,
      "mandatory_at_input": true,
      "output_only": false,
      "name": "identifying_company",
      "datatype": "string",
      "type": "input",
      "id": 165,
      "editable": false
    },
    {
      "mandatory_at_output": true,
      "mandatory_at_input": true,
      "output_only": false,
      "name": "name",
      "datatype": "string",
      "type": "input",
      "editable": true,
      "id": 166
    },
    {
      "output_only": false,
      "name": "birth_name",
      "mandatory_at_output": true,
      "mandatory_at_input": true,
      "type": "input",
      "editable": true,
      "id": 167,
      "datatype": "string"
    },
    {
      "name": "birth_place",
      "output_only": false,
      "mandatory_at_input": true,
      "mandatory_at_output": true,
      "id": 168,
      "editable": true,
      "type": "input",
      "datatype": "string"
    },
    {
      "output_only": false,
      "name": "birth_date",
      "mandatory_at_output": true,
      "mandatory_at_input": true,
      "type": "input",
      "editable": true,
      "id": 169,
      "datatype": "date"
    },
    {
      "datatype": "string",
      "type": "input",
      "id": 170,
      "editable": true,
      "mandatory_at_output": true,
      "mandatory_at_input": true,
      "output_only": false,
      "name": "mothers_maiden_name"
    },
    {
      "datatype": "string",
      "editable": true,
      "id": 171,
      "type": "input",
      "mandatory_at_input": true,
      "mandatory_at_output": true,
      "name": "permanent_zip",
      "output_only": false
    },
    {
      "mandatory_at_input": true,
      "mandatory_at_output": true,
      "name": "permanent_country",
      "output_only": false,
      "datatype": "string",
      "id": 172,
      "editable": true,
      "type": "input"
    },
    {
      "type": "input",
      "id": 173,
      "editable": true,
      "datatype": "string",
      "name": "permanent_city",
      "output_only": false,
      "mandatory_at_output": true,
      "mandatory_at_input": true
    },
    {
      "id": 174,
      "editable": true,
      "type": "input",
      "datatype": "string",
      "output_only": false,
      "name": "permanent_street",
      "mandatory_at_input": true,
      "mandatory_at_output": true
    },
    {
      "name": "temporary_zip",
      "output_only": false,
      "mandatory_at_input": true,
      "mandatory_at_output": true,
      "editable": true,
      "id": 175,
      "type": "input",
      "datatype": "string"
    },
    {
      "output_only": false,
      "name": "temporary_country",
      "mandatory_at_input": true,
      "mandatory_at_output": true,
      "editable": true,
      "id": 176,
      "type": "input",
      "datatype": "string"
    },
    {
      "mandatory_at_output": true,
      "mandatory_at_input": true,
      "output_only": false,
      "name": "temporary_cit",
      "datatype": "string",
      "type": "input",
      "id": 177,
      "editable": true
    },
    {
      "mandatory_at_output": true,
      "mandatory_at_input": true,
      "name": "temporary_street",
      "output_only": false,
      "datatype": "string",
      "type": "input",
      "editable": true,
      "id": 178
    },
    {
      "type": "input",
      "id": 179,
      "editable": true,
      "datatype": "string",
      "name": "email",
      "output_only": false,
      "mandatory_at_output": true,
      "mandatory_at_input": true
    },
    {
      "output_only": false,
      "name": "phone",
      "mandatory_at_output": true,
      "mandatory_at_input": true,
      "type": "input",
      "editable": true,
      "id": 180,
      "datatype": "string"
    },
    {
      "datatype": "string",
      "content": [
        {
          "label": "útlevél",
          "value": "passport"
        },
        {
          "value": "license",
          "label": "jogosítvány"
        },
        {
          "label": "személyi igazolvány",
          "value": "identity card"
        }
      ],
      "type": "choice",
      "id": 181,
      "editable": true,
      "mandatory_at_output": true,
      "mandatory_at_input": false,
      "selection": "single",
      "name": "id_card_type",
      "output_only": true
    },
    {
      "type": "input",
      "editable": true,
      "id": 182,
      "datatype": "string",
      "name": "id_card_number",
      "output_only": true,
      "mandatory_at_output": true,
      "mandatory_at_input": false
    },
    {
      "datatype": "string",
      "type": "input",
      "editable": true,
      "id": 183,
      "mandatory_at_output": true,
      "mandatory_at_input": false,
      "output_only": true,
      "name": "address_card_number"
    },
    {
      "datatype": "string",
      "id": 184,
      "editable": true,
      "type": "input",
      "mandatory_at_input": false,
      "mandatory_at_output": true,
      "output_only": false,
      "name": "nationality"
    },
    {
      "output_only": true,
      "name": "public_figure",
      "selection": "single",
      "mandatory_at_input": false,
      "mandatory_at_output": true,
      "editable": true,
      "id": 185,
      "type": "choice",
      "content": [
        {
          "value": "customer",
          "label": "célszemély"
        },
        {
          "value": "family member",
          "label": "családtag"
        }
      ],
      "datatype": "string"
    },
    {
      "type": "input",
      "editable": false,
      "id": 186,
      "datatype": "string",
      "name": "external_id",
      "output_only": false,
      "mandatory_at_output": true,
      "mandatory_at_input": false
    },
    {
      "mandatory_at_output": true,
      "mandatory_at_input": true,
      "output_only": false,
      "name": "simplified_identification",
      "datatype": "boolean",
      "type": "input",
      "editable": false,
      "id": 187
    },
    {
      "type": "input",
      "editable": false,
      "id": 188,
      "datatype": "date",
      "output_only": false,
      "name": "preferred_time",
      "mandatory_at_output": true,
      "mandatory_at_input": false
    },
    {
      "type": "input",
      "id": 189,
      "editable": true,
      "datatype": "boolean",
      "output_only": true,
      "name": "statements_accepted",
      "mandatory_at_output": true,
      "mandatory_at_input": false
    },
    {
      "datatype": "boolean",
      "id": 190,
      "editable": true,
      "type": "input",
      "mandatory_at_input": false,
      "mandatory_at_output": true,
      "output_only": true,
      "name": "recordings_confirmed"
    },
    {
      "datatype": "boolean",
      "id": 191,
      "editable": true,
      "type": "input",
      "mandatory_at_input": false,
      "mandatory_at_output": true,
      "name": "data_check_completed",
      "output_only": true
    }
  ]
}

Részletek: A válaszban a payload elem tartalmazza a kampányban található oszlopokat. Az oszlopok tulajdonságai:

name: a neve
datatype: adattípus
id: rendszerben használt azonosító
type: mező típusa
content (choice type esetén): a tartalmazott elemek
editable: módosítható
output_only: betöltésnél, rekordmódosításnál nem módosítható, csak a rekord adatainak lekérdezésekor jelenik meg.
mandatory_at_input: rekord létrehozásnál kötelező mező
mandatory_at_output: rekord lekérdezésében kötelezően megjelenik

Webhookok

A Comnica bizonyos eseményekre tud egy távoli URL meghívásával reagálni. Azon a címen valamilyen HTTP szervernek kell figyelnie, és JSON bodyval rendelkező POST kéréseket fogadnia. A Comnica rendszere csak egy requestet küld minden eseményről és nem figyeli, hogy arra milyen válasz érkezik a beállított végponttól, és ennek megfelelően nem is próbálkozik újra az adott eseménnyel kapcsolatos figyelmeztetéssel.

Beállítás

Minden CC (telefonos) és azonosítás (videó, NRTI) projekthez lehet külön rendelni 1 darab webhook URL-t, például https://api.example.com:8080/comnica-webhook-receiver/

Egyelőre más konfigurációs lehetőség nincs.

Formátum

A webhook hívás bodyja UTF-8 kódolású JSON string. Három kulccsal rendelkezik.

event: az esemény, ami miatt a hívás érkezett, például cc.record.save, mindig ki van töltve
event_reason: egyfajta megkülönböztető jelzés az adott eseményen belül, például operator.termination, lehet null
payload: objektum, benne valamennyi adattal, ami szükségesnek és elégségesnek tűnik. Legalább {} az értéke.

{
  "event": "i12n.record.state.change",
  "event_reason": null,
  "payload": {
    "record_id": 42,
    "previous_state": "active",
    "new_state": "reviewing"
  }
}

Tartalom

A lehetséges események jelenleg a következők:

CC rekord mentése

event: cc.record.save
event_reason:
- site.edit — az adminfelületen szerkesztették
- operator.save — az operátori kliensben mentették el a rekordot
- operator.termination — az operátori kliensben elmentették és lezárták a rekordot
payload:
- record_id — a rekord azonosítója
- termination_id — a termináció azonosítója vagy null
- terminating_code — a termináció neve vagy null

Azonosítás állapotváltása

event: i12n.record.state.change
event_reason:
- null — általában
- timeout — a rekord készen állt arra, hogy az ügyfél az azonosítást megkezdje, de az időlimiten belül ez nem történt meg
- timeout_before_ready — a rekord nem került használható állapotba az időlimiten belül
- review_timeout — a rekord ellenőrzése nem történt meg az időlimiten belül
payload:
- record_id — a rekord azonosítója
- previous_state — az előző állapot
- new_state — az új állapot