API pro práci s hovory

Součást Odorik.cz API určená pro práci s telefonními hovory.

Callback

POST /callback

  • požadavek k iniciování zpětného volání (callback)
  • povinné parametry:
    • caller: telefonní číslo, se kterým se pokusí spojit ústředna Odorik.cz
    • recipient: telefonní číslo, se kterým budete spojeni po navázání hovoru mezi ústřednou a číslem předanným pomocí parametru caller
  • nepovinné parametry:
    • delayed - opožděný callback; možné hodnoty jsou buď jedno číslo určující počet minut, o kolik bude callback zdržen, anebo přesné datum pro vytvoření callbacku ve formátu dateTime z XML Schema (například: 2036-07-16T08:12:14Z)
    • line - v případě přihlášení přes API heslo určuje linku, přes kterou bude callback realizován (u této linky bude callback evidován ve výpisu hovorů, příjemci callbacku se zobrazí při volání číslo přiřazené k lince, …)
    • simple - v případě předání hodnoty „true“ nebude moci caller pomocí hvězdičky a DTMF tónu vytočit jiné číslo; zároveň nedochází ke snaze využít ke spojení další operátory, pokud první operátor selhal nebo hovor nespojil; implicitní je hodnota „false“. Pokud si tedy někdo objedná hovor a ten hovor pak odmítne, nebude se pokus opakovat.
  • formát odpovědi: plain-text
  • možné odpovědi:
    • callback_ordered
    • successfully_enqueued
    • error callback_failed - požadavek se nepodařilo předat Odorik.cz ústředně
    • error missing_argument <seznam_chybejicich_argumentu>
    • error invalid_delay_format
    • error delayed_into_past
    • error invalid_line
  • POZOR: požadavek se předává ústředně Odorik.cz, a pokud zadáte neexistující číslo, nebude Váš hovor spojen i přesto, že API vrátí odpověď calback_ordered
  • vyžaduje autentizaci

Historie hovorů

GET /calls.csv, GET /calls.json, GET /calls.xml

  • výpis hovorů
  • povinné parametry:
    • from, to: časové rozmezí hovorů; řetězec formátovaný jako dateTime z XML Schema (například: 2013-06-05T11:15:00+02:00)
  • nepovinné parametry:
    • direction: in/out/redirected; filtr na příchozí/odchozí/přesměrované hovory
    • line: vrátit jen na hovory na dané lince
    • min_length, max_length: omezit výpis podle délky hovoru v sekundách
    • min_price, max_price: omezit podle ceny hovoru v korunách
    • status: answered/missed; filtr na zvednuté/zmeškané hovory
    • phone_number_filter: prefix nebo celé telefonní číslo (např. 0049 nebo 00420533533533); filtruje podle source_number i destination_number (OR)
    • sip_ids: pokud je předána hodnota true, přidají se k záznamům o hovorech atributy sip_in_call_id a sip_out_call_id
  • stránkování:
    • na jeden dotaz vracíme maximálně 2000 hovorů, při větším počtu je potřeba použít stránkování
    • parametry:
      • page_size: (maximální) počet vracených hovorů na jednu stránku
      • page: vrátit jinou než první stránku (indexujeme od 1)
    • celkový počet stránek pro daný request vracíme v HTTP hlavičce Odorik-Pages
  • vyžaduje autentizaci
  • příklad odpovědi (JSON):
[{"id": 98292358,
  "redirection_parent_id": 98292356,
  "date": "2014-10-01T11:28:31Z",
  "direction": "redirected",
  "source_number": "00420555444333",
  "destination_number": "*300000",
  "destination_name": "Česká rep. - * v síti",
  "length": 362,
  "ringing_length": 8,
  "status": "answered",
  "price": 0.0,
  "price_per_minute": 0.0,
  "balance_after": 554.0288,
  "line": 403366,
  "recording": null}]

Nahrané hovory

GET /call_recordings/<call_id>.<ext>

  • stažení audio souboru s nahraným hovorem
  • vyžaduje autentizaci
  • k dispozici ke stažení jsou nahrávky těch hovorů, které v historie hovorů mají u atributu recording nenulovou
  • <call_id> je id záznamu z historie hovorů; <ext> podle zvoleného formátu pro nahrávání, v historii hovorů je uveden v objektu u atributu recording (jen JSON a XML)
  • nahrávání hovorů se zapíná v uživatelském rozhraní (průvodce nastavením ⇒ volání z internetu ⇒ nastavení linky), email pro zasílání nahraných hovorů musí obsahovat položku „#store“. Tedy do položky, kde se normálně dává jeden či více emailů oddělených čárkou, napíšete místo emailu jen #store. Možné je mít na tomto místě též jeden či více emailů a navíc čárkou oddělené klíčové slovo #store, jakoby to byl další email. Možné je nastavit kolik dní mají být emaily uloženy.
  • příklad skriptu pro automatické stahování hovorů je k dispozici v ukázkách použití API

Právě probíhající hovory

GET /active_calls.json

  • výpis právě probíhajících hovorů
  • vyžaduje autentizaci
  • možné chybové stavy:
    • unauthorized
  • příklad odpovědi:
[ { "id":14990661,
    "source_number":"00420533533013",
    "destination_number":"00420910110006",
    "destination_name":"Česko v síti 910-test- přesměrováno",
    "start_date":"2013-08-15T06:34:43Z",
    "answer_date":"2013-08-15T06:34:46Z",
    "price_per_minute":0.0,
    "line":403366 } ]

DELETE /active_calls/<id>.json

  • zavěšení hovoru; <id> je atribut „id“ z výpisu právě probíhajících hovorů
  • vyžaduje autentizaci
  • možné chybové stavy:
    • unauthorized

Statistika

GET /call_statistics.json

  • statistika hovorů za zvolené období
  • povinné parametry:
    • from, to: časové rozmezí hovorů; řetězec formátovaný jako dateTime z XML Schema (například: 2013-06-05T11:15:00+02:00)
  • nepovinné parametry:
    • direction: in/out/redirected; filtr na příchozí/odchozí/přesměrované hovory
    • line: vrátit jen na hovory na dané lince
    • min_length, max_length: omezit výpis podle délky hovoru v sekundách
    • min_price, max_price: omezit podle ceny hovoru v korunách
  • vyžaduje autentizaci
  • příklad odpovědi:
{ "incoming":{"count":140,"length":27405,"price":0.0},
  "outgoing":{"count":118,"length":26808,"price":56.9056},
  "redirected":{"count":14,"length":1696,"price":16.6772} }

GET /call_statistics/by_destination.json

  • statistika hovorů za zvolené období podle destinací
  • povinné parametry:
    • from, to: časové rozmezí hovorů; řetězec formátovaný jako dateTime z XML Schema (například: 2013-06-05T11:15:00+02:00)
  • nepovinné parametry:
    • direction: in/out/redirected; filtr na příchozí/odchozí/přesměrované hovory
    • line: vrátit jen na hovory na dané lince
    • min_length, max_length: omezit výpis podle délky hovoru v sekundách
    • min_price, max_price: omezit podle ceny hovoru v korunách
  • vyžaduje autentizaci
  • příklad odpovědi:
[ {"destination":"Česká rep. - mobil","count":10,"length":1234,"price":12.1344,"price_per_minute":0.59,"direction":"out"},
  {"destination":"Česká rep. - mobil","count":14,"length":1696,"price":16.6772,"price_per_minute":0.59,"direction":"redirected"},
  {"destination":"Česká rep. - mobil","count":8,"length":307,"price":7.6239,"price_per_minute":1.49,"direction":"out"},
  {"destination":"Česká rep. - odorikmobil","count":3,"length":105,"price":1.0325,"price_per_minute":0.59,"direction":"out"},
  {"destination":"Česká rep. - odorikpevna","count":54,"length":2603,"price":25.5958,"price_per_minute":0.59,"direction":"out"},
  {"destination":"Česká rep. - pevna","count":2,"length":99,"price":2.4585,"price_per_minute":1.49,"direction":"out"},
  {"destination":"Česká rep. - pevná - špička","count":2,"length":987,"price":8.0605,"price_per_minute":0.49,"direction":"out"},
  {"destination":"Česko v síti","count":106,"length":19028,"price":0.0,"price_per_minute":0.0,"direction":"in"},
  {"destination":"Česko v síti","count":39,"length":21473,"price":0.0,"price_per_minute":0.0,"direction":"out"},
  {"destination":"Odorik.cz mobil","count":34,"length":8377,"price":0.0,"price_per_minute":0.0,"direction":"in"} ]

GET /call_statistics/missed_calls.json

  • statistika zmeškaných hovorů za zvolené období
  • povinné parametry:
    • from, to: časové rozmezí hovorů; řetězec formátovaný jako dateTime z XML Schema (například: 2013-06-05T11:15:00+02:00)
  • vyžaduje autentizaci
  • příklad odpovědi:
[ {"destination_number":"00420533533533","count":2},
  {"destination_number":"00420533999999","count":3} ]
 
api/calls.txt · Poslední úprava: 2017/09/29 23:22 autor: misa