====== API pro práci s hovory ====== Součást [[:api|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 [[http://www.w3.org/TR/xmlschema-2/#dateTime|dateTime z XML Schema]] (například: //2036-07-16T08:12:14Z//); pozor na znak "+" (viz [[wp>Percent-encoding]]) * **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 // * //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 [[:api#autentizace|autentizaci]] ===== Historie hovorů ===== === GET /calls.csv, GET /calls.json, GET /calls.xml === * výpis hovorů * povinné parametry (jedna ze dvou možností níže): - **from**, **to**: časové rozmezí hovorů; řetězec formátovaný jako [[http://www.w3.org/TR/xmlschema-2/#dateTime|dateTime z XML Schema]] (například: //2013-06-05T11:15:00+02:00//); pozor na znak "+" (viz [[wp>Percent-encoding]]) - **since_id**: ID posledního staženého hovoru - vhodné pro periodické stahování nových záznamů * 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// * **include_sms**: pokud je předána hodnota true, vrací se zároveň i SMS zprávy a není potřeba načítat SMS samostatně (pomocí GET /sms.csv (/sms.xml, /sms.json)) * 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 [[:api#autentizace|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}] ===== Právě probíhající hovory ===== === GET /active_calls.json === * výpis právě probíhajících hovorů * vyžaduje [[:api#autentizace|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/.json === * zavěšení hovoru; je atribut "id" z výpisu právě probíhajících hovorů * vyžaduje [[:api#autentizace|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 [[http://www.w3.org/TR/xmlschema-2/#dateTime|dateTime z XML Schema]] (například: //2013-06-05T11:15:00+02:00//); pozor na znak "+" (viz [[wp>Percent-encoding]]) * 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 [[:api#autentizace|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 [[http://www.w3.org/TR/xmlschema-2/#dateTime|dateTime z XML Schema]] (například: //2013-06-05T11:15:00+02:00//); pozor na znak "+" (viz [[wp>Percent-encoding]]) * 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 [[:api#autentizace|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 [[http://www.w3.org/TR/xmlschema-2/#dateTime|dateTime z XML Schema]] (například: //2013-06-05T11:15:00+02:00//); pozor na znak "+" (viz [[wp>Percent-encoding]]) * vyžaduje [[:api#autentizace|autentizaci]] * příklad odpovědi: [ {"destination_number":"00420533533533","count":2}, {"destination_number":"00420533999999","count":3} ]