Možnosti integrace telefonní ústředny Telfa s vašimi systémy
Obecné
Ověřování probíhá pomocí HTTP Basic, použijte váš libovolný administrátorský účet. Vždy je třeba nastavit Accept hlavičku na application/xml nebo přidat .xml za URL (případně ekvivalent application/json resp. .json pro JSON), viz příklady. Dále je nutné nastavit správnou hodnotu hlavičky Content-Type, v případě XML na "application/xml", v případě JSON opět "application/json".
Základní URL je vždy https://telfa.cz, za něj přidejte příslušnou cestu, viz dále v dokumentaci.
REST API
Click to call
POST /calls.xml?number=245008328
Vytočí Telfa účet uživatele, pod kterým je URL zavoláno a spojí hovor s číslem předaným jako parametr. Je-li Telfa účet nedostupný, použije se nastavený mobilní telefon uživatele.
Zavolej a přečti text
POST /calls/announce.xml?number=245008328&text=ahoj%20pane
Vytočí zadané telefonní číslo a přečte volanému zadaný text pomocí řečového sytentizéru (text2speech).
Aktuálně probíhající hovor
GET /calls/current.xml?login=jan.kubr.livispace.cz
Vrátí XML s informacemi o právě probíhajícím hovoru uživatele s daným loginem:
<call>
<caller_number>777123456</caller_number>
<dialed_number>245008328</dialed_number>
<start>2009-10-11T13:41:59+02:00</start>
<answered_at>2009-10-11T13:42:10+02:00</answered_at>
<transfer_description>Nova objednavka</transfer_description>
</call>
Seznam všech hovorů
GET /calls.xml?from=2009-10-11+10%3A30
Vrátí XML obsahující všechny hovory od 11.10.2009 10:30. Možno využít například pro notifikace o zmeškaných hovorech:
<calls type="array">
<call>
<answered_at/>
<answered_by_user_id/>
<bridge_start_at>2009-10-11T13:42:19+02:00</bridge_start_at>
<caller_number>777123456</caller_number>
<dialed_number>245008328</dialed_number>
<created_at>2009-10-11T13:41:59+02:00</created_at>
<hungup_at/>
<id>13576</id>
<inbound>true</inbound>
<outbound_from_external_number/>
<recorded>true</recorded>
<task_id/>
<transfer_description>Nova objednavka</transfer_description>
<transferred_to_number/>
<voice_mail_file_name/>
<recording_file_name>/calls/13110/recording</recording_file_name>
</call>
</calls>
Hovory jsou vždy stránkovány po 20 záznamech, pro vrácení všech stran navyšujte parametr page do té doby, než se vám vrátí stránka s méně než 20 záznamy nebo stránka prázdná:
GET /calls.xml?from=2009-10-11+10%3A30&page=15
Pokud vrátí prázdnou stránku:
<nil-classes type="array"/>
Tato data lze získat i ve formátu JSON:
GET /calls.json?from=2009-10-11+10%3A30
[{"answered_by_user_id":null,
"answered_at":null,
"inbound":true,
"hungup_at":null,
"caller_name":null,
"recording_file_name":null,
"created_at":"2009/10/11 13:41:59+02:00",
"outbound_from_external_number":null,
"bridge_start_at":"2009/10/11 13:42:19+02:00",
"caller_number":"777123456",
"recorded":true,
"voice_mail_file_name":null,
"transfer_description":"Nova objednavka",
"task_id":null,
"id":13576,
"dialed_number":"245008328",
"transferred_to_number":null}]
Plány hovorů
GET /recipes.json
Vrátí JSON s plány hovorů pro přidělená čísla. Plány jsou stránkovány po 20 záznamech. Pro vrácení všech stran navyšujte parametr page do té doby, než se vám vrátí stránka s méně než 20 záznamy nebo stránka prázdná.
[{"contact_group_id":null, // ID skupiny kontaktů, je-li tento plán specifický pouze pro některou skupinu kontaktů
"number":"212212212", // Číslo, kterému je plán hovoru přiřazen
"number_id":10, // ID čísla, kterému je plán hovoru přiřazen
"name":null, // Jméno plánu, jedná-li se o opakující se část (v takovém případě je položka number prázdná)
"id":534, // ID plánu
"description":"zakaznicka linka"}] // Popis plánu hovoru
GET /recipes/534.json
Vrátí detail plánu hovoru.
{"number":"245008328",
"number_id":10,
"contact_group_id":null,
"name":null,
"id":534,
"items":
[{"remove_from_queue_after":null, //Po kolika sekundách se má pokračovat dalším krokem, pokud tento krok je "Zařadit do fronty skupiny"
"transfer_user_id":null, // ID uživatele, na kterého se má hovor přepojit při akci "transfer" nebo "transfer_to_mobile"
"action":"play", // Jméno akce, kterou tato položka plánu vykonává, seznam akcí níže
"menu_tries":1, // Počet možných chybných pokusů při akci "menu"
"phone_number":null, // Telefonní číslo, na které se má hovor přepojit při akci "call"
"url":null, // URL, na které se má předat řízení při akci "api"
"run_on_days":"every_day", // Časové omezení položky, může být jedna z "every_day" (každý den), "working_days" ( pracovní dny), "non_working_days" (v nepracovní dny), "business_hours" (v pracovní dobu), "outside_business_hours" (mimo nepracovní dobu)
"menu_timeout":0, // Počet sekund, které se čekají na zadání volby při akci "menu"
"recording_id":2722, // ID nahrávky, která se má přehrát v kroku "play", případně přehrávat jako zvonění
"ringing_length":20, // Délka zvonění v případě akce přepojování
"sequence":1, // Pořadí kroku v plánu hovoru
"run_before":"00:00", // Časové omezení, do kdy v rámci dne se má položka provádět
"transfer_description":null, // Popis přepojení, zobrazuje se např. na displeji telefonu
"continue_with_recipe_id":null, // ID plánu hovoru, kterým se má pokračovat v případě položky typu "continue_with"
"run_after":"00:00", // Časové omezení, od kdy v rámci dne se má položka provádět
"id":119, // ID položky
"group_call_kind":null, // Druh vytáčení hovorů na skupinu uživatelů v případě položky "transfer_to_group", může být jedna z "in_order" (dle pořadí ve skupině), "least_idle" (nejdéle bez hovoru) nebo "at_once" (všichni najednou)
"call_group_id":null, // Skupina uživatelů, na kterou se mají hovory směrovat v případě položky "transfer_to_group", případně přijemci hlasové zprávy v případě akce "voice_mail"
"text_to_speak":null, // Text, který se má přečíst při akci "read"
"female": true // Má-li být hlas pro akci "read" ženský nebo mužský
}]}
POST /recipe_items.json
Založí novou položku plánu hovoru a umístí jí na jeho konec. Vrací buď 200 OK a v těle JSON s daty položky nebo 422 Unprocessable Entity a v těle seznam chyb. V těle požadavku musí být minimálně:
"recipe_item":{
"recipe_id":534, // ID plánu hovoru, do kterého se má položka zařadit
"action":"play"// Název akce, kterou bude položka provádět, seznam akcí níže
}
Dále zde mohou být libovolné další položky, které jsou vidět výše ve výpisu detailu plánu hovoru v položce "items".
PUT /recipe_items/5304.json
Aktualizuje položku plánu hovoru s daným ID. Tělo požadavku vypadá obdobně, jako v případě vytváření položky.
DELETE /recipe_items/5304.json
Smaže položku plánu hovoru s daným ID.
Seznam možných akcí položek plánů hovorů
| Kód akce | Popis |
|---|---|
| play | Přehrát |
| read | Přečíst |
| menu | Výběr |
| transfer | Přepojit na VoIP telefon |
| transfer_to_mobile | Přepojit na mobilní telefon |
| transfer_to_group | Zařadit do fronty skupiny |
| call | Vytočit |
| voice_mail | Nahrát zprávu |
| api | Předat řízení |
| mobility_extension | Spojit s číslem |
| continue_with | Pokračuj opakující se částí |
Čísla
GET /numbers/10.json
Vrátí detail přiděleného telefonního čísla. Funkcionalita ring_hook_url a transfer_hook_url je vysvětlena níže v části Webhooky.
{"id":"10",
"number":"212212212",
"ring_hook_url":null,
"transfer_hook_url":null}
PUT /numbers/10.json
Aktualizuje číslo. Vrací buď 200 OK a v těle JSON s daty čísla nebo 422 Unprocessable Entity a v těle seznam chyb. Měnit lze pouze ring_hook_url nebo transfer_hook_url.
"number":{"ring_hook_url":"https://moje.url.cz",
"ring_hook_url": null}
Webhooky
Chcete vašim operátorům zobrazit informace o volajícím ve chvíli, kdy jím zvoní nový hovor? Lze využít tzv. webhooku, tedy URL, na které Telfa pošle přes HTTP POST informace o právě zvonícím hovoru.
<call>
<id>345032</id>
<caller_number>777123456</caller_number>
<dialed_number>245008328</dialed_number>
<start>2009-10-11T13:41:59+02:00</start>
<ring_start_at>2009-10-11T13:42:05+02:00</ring_start_at>
<transferred_to>jan.kubr.livispace.cz</transferred_to>
<transfer_description>Nova objednavka</transfer_description>
</call>
Podobné XML můžete dostat i ve chvíli, kdy operátor hovor zvedne:
<call>
<id>345032</id>
<caller_number>777123456</caller_number>
<dialed_number>245008328</dialed_number>
<start>2009-10-11T13:41:59+02:00</start>
<answered_at>2009-10-11T13:42:10+02:00</answered_at>
<answered_by_login>jan.kubr.livispace.cz</answered_by_login>
<transfer_description>Nova objednavka</transfer_description>
</call>
Webhooky se dají nastavit buď centrálně pro všechna vaše čísla (na vyžádání) nebo přes API pomocí aktualizace čísla, viz předchozí sekce. Pokud si chcete tyto informace od serveru vyžádat sami, je to možné, opět viz předchozí sekce.
Plné ovládání hovoru přes API
V plánu hovoru:
Volá URL:
POST http://example.com/telfa_handler?vlastni=hodnota&caller_number=777123321&called_number=245008328
Při položení hovoru přidá parameter hangup=true, tj.:
POST http://example.com/telfa_handler?vlastni=hodnota&caller_number=777123321&called_number=245008328&hangup=true
Akce
Jako odpověď na výše uvedený dotaz je třeba poslat JSON s akcí, která se má vykonat. Po skončení akce je výše uvedené URL zavoláno znovu (s výjimkou akce Položit).
Zvednout:
{
"action": "answer"
}
Položit:
{
"action": "hangup"
}
Přehrát:
{
"action": "play",
"recording_id": "4"
}
Přepojit:
{
"action": "transfer",
buď:
"transfer_user_login": "jan.kubr.livispace.cz",
nebo:
"transfer_user_id": "2",
#nepovinne:
"recording_id": "2",
"transfer_description": "Fakturace",
"ringing_length": "60",
}
Vytočit:
{
"action": "call",
"number": "777123321",
#nepovinne:
"recording_id": "2",
"ringing_length": "60",
}
Nahrát zprávu:
{
"action": "voice_mail",
"call_group_id": "2",
}
{
"action": "voice_mail",
"flempo_team_id": "12",
}
Výběr:
{
"action": "menu",
"recording_id": => "4",
#nepovinne:
"menu_timeout": "10",
"max": "1",
"terminator": "#"
}
Předání řízení zpět do statického plánu hovoru:
{
"action": "resign",
}
Závěr
Dokumentace API nemusí být úplná, pokud vám něco chybí, kontaktujte nás. Funkce webhook a plná kontrola vyžadují aktivaci z naší strany.
Zavolejte nám: 840 666 777