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. Jako uživatelské jméno se používá email uživatele se @ (oproti formátu s tečkou u VoIP telefonů). Vždy je nutné nastavit správnou hodnotu hlavičky Content-Type, v případě XML na "application/xml", v případě JSON "application/json".
Základní URL závisí na umístění vašeho účtu. Na tomto serveru je to https://telfa.cz. Adresa může být ale také např. https://www4.telfa.cz nebo https://www2.telfa.cz atd., podívejte se kam jste přesměrování po přihlášení do webového rozhraní, stejné URL se používá i pro API.
Za tuto základní URL přidejte příslušnou cestu, viz dále v dokumentaci.
 

REST API - funkce po skupinách

Hovory

  • vytočení hovoru
  • automatické hovory - zavolej a proveď akci
  • přehraj hlášku do hovoru
  • přepojení hovoru
  • ukončení hovoru
  • výpisy hovorů a stažení nahrávek
  • Uživatelé

  • stav uživatelů
  • informace o uživateli
  • přihlášení/odhlášení operátorů
  • nastavení čísla pro odchozí hovory
  • Kontakty

  • výpis kontaktů
  • vytvoření, upravení a mazání kontaktů
  • SMS zprávy

  • odeslání SMS zprávy
  • příjem SMS zpráv
  • mazání SMS zpráv
  • fronta SMS zpráv
  • Hlášky

  • vygenerování hlášky z textu pomocí Text To Speech
  • Čísla a plány hovorů

  • výpis čísel, plánů hovorů a jejich kroků
  • vytváření a úprava položek plánu hovoru
  • Webhooky

  • typy webhooků a jejich popis
  • nastavení webhooků
  • Ovládání hovorů v reálném čase

  • popis realtime ovládání
  • akce e jejich použití
  • Závěr


     

    Vytváření a ukončování hovorů

    Click to call

    POST /calls.xml?number=245008328&method=both

    Vytočí VoIP telefon nebo mobil uživatele, pod kterým se autorizujete při volání URL a spojí hovor s číslem předaným jako parametr. Parametr "method" je volitelný a jeho možné hodnoty jsou následující:

  • prázdný nebo neuveden - nejprve se vytočí VoIP telefon uživatele a pakliže je nedostupný, vytočí se mobil uživatele
  • voip
    vytočí se VoIP telefon uživatele, pakliže je nedostupný nic se dál neděje
  • mobile
    vytočí se mobil uživatele, pakliže je nedostupný nic se dál neděje
  • both
    vytočí zároveň VoIP telefon i mobil uživatele, hovor vyhrává ten, který je dřív zvednut
  • php příklad >>

    Pozn.: parametr "method" je k dispozici pouze na serverech www2 a vyšších
     

    Automatické hovory - zavolej a proveď akci

    POST /calls/announce.xml?number=245008328&text=ahoj%20pane
    nebo
    POST /calls/announce.xml?number=245008328&recording_id=10
    nebo
    POST /calls/announce.xml?number=245008328&recipe_id=28

    Vytočí zadané telefonní číslo a přečte volanému zadaný text pomocí řečového sytentizéru (text musí být URL encoded), přehraje zadanou hlášku anebo pokračuje předem připravenou Opakující se částí.

    php příklad >>


    Přehrání hlášky do probíhajícího hovoru

    POST /calls/play_recording.xml

    Přehraje hlášku do probíhajícího hovoru, zmixuje ji se zvukem hovoru, ten se tedy nepřeruší. Volitelně přehraje pouze volajícímu nebo pouze volanému. API request skončí ihned, nečeká se na dokončení přehrávání hlášky.

    Na tuto URL je potřeba poslat XML s následující strukturou (parametr side je volitelný a může nabývat hodnot "both" - přehrát oběma stranám (výchozí), "caller" - přehrát pouze volajícímu, "called" - přehrát pouze volanému):

        <play_recording>
          <call_id>1</call_id>
          <recording_id>6</recording_id>
          <side>both</side>
        </play_recording>
    		
    php příklad >>


    Přepojení probíhajícího hovoru

    POST /calls/transfer_call.xml

    Přepojí probíhající hovor na zaslané ID opakující se části, kterou předem vytoříte přes webové rozhraní v sekci Plán hovoru.
    Pakliže hovor aktuálně vyzvání operátorovi na telefonu anebo je již spojen, k přepojení dojde až po položení hovoru nebo timeoutu vyzvánění.
    V ostatních případech dojde k přepojení okamžitě (při čekání ve frontě, přehrávání hlášky, nahrávání hlasové zprávy).

    Na tuto URL je potřeba poslat XML s následující strukturou:

        <transfer_call>
          <call_id>1</call_id>
          <continue_with_recipe_id>6</continue_with_recipe_id>
        </transfer_call>
    		
    php příklad >>


    Ukončení hovoru

    POST /calls/interrupt.xml

    Přeruší hovor, volitelně přehraje hlášku (je-li zadaná) a poté hovor ukončí.

    Na tuto URL je potřeba poslat XML s následující strukturou (parametr recording_id je volitelný):

        <interrupt_call>
          <id>1</id>
          <recording_id>6</recording_id>
        </interrupt_call>
    		
    php příklad >>

    Výpis hovorů a stažení nahrávek

    Aktuálně probíhající hovor uživatele

    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>
          
    vysvětlení polí >>   php příklad >>


    Seznamy hovorů

    Aktuálně probíhající hovory
    GET /calls/all_current.xml
    Výpis všech hovorů
    GET /calls.xml?from=2013-12-11+10%3A30

    Vrátí XML obsahující všechny hovory, které začaly nebo byly položeny od 11.12.2013 10:30.
    Možno využít například pro notifikace o zmeškaných hovorech. Při pravidelném načítání prosím zvažte, jestli nestahujete zbytečně velké období.

          <calls type="array">
            <call>
              <announcement_id/>
              <answered_at/>
              <answered_by_user_id/>
              <bridge_start_at>2009-10-11T13:42:19+02:00</bridge_start_at>
              <group_start_at></group_start_at>
              <caller_number>777123456</caller_number>
              <call_group_id>5</call_group_id>
              <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/>
              <telfa_user_id>1</telfa_user_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>
          
    vysvětlení polí >>   způsoby využití >>   php příklad >>
     

    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=2013-12-11+10%3A30&page=3

    Dokud nevrátí prázdnou stránku:

            <nil-classes type="array"/>
          

    Pro načtení detailu pouze jednoho hovoru pomocí jeho ID použijte:

    GET /calls.xml?id=3

    Tato data lze získat i ve formátu JSON:

    GET /calls.json?from=2009-10-11+10%3A30
    [{"announcement_id":null,
    "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",
    "group_start_at":null,
    "call_group_id":null,
    "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,
    "telfa_user_id":null}]
    vysvětlení polí >>
     

    Stažení nahrávky hovoru

    GET calls/400/recording.xml

    Vrátí nahrávku hovoru, kterou lze uložit nebo nabídnout ke stažení ve vlastní aplikaci.

    php příklad >>
     

    Informace o uživatelích a jejich nastavení

    Zobrazit seznam uživatelů a jejich stav

    GET /telfa_users/status.xml
    nebo
    GET /telfa_users/status.json

    Vypíše seznam všech uživatelů, jestli jsou přihlášeni nebo odhlášeni a odkdy, a také jestli jsou dostupní pro příjem hovorů nebo jsou zrovna obsazeni hovorem.
    Vrací XML nebo JSON následující struktury:

          <telfa-users type="array">
            <telfa-user>
              <available type="boolean">true</available>
              <email>marek@livispace.cz</email>
              <id type="integer">4516</id>
              <name>Marek Livispace</name>
              <presence-changed-at type="datetime">2014-02-24T10:44:49Z</presence-changed-at>
              <present type="boolean">true</present>
            </telfa-user>
          </telfa-users>
    		
    nebo
        { "present":true,
          "name":"Marek Livispace",
          "presence_changed_at":"2014/06/16 23:41:08 +0000",
          "available":true,
          "id":744,
          "email":"marek@livispace.cz" }
        
    vysvětlení polí >>   php příklad XML >>   php příklad JSON >>
     

    Pozn.: funkce je k dispozici pouze na serverech www2 a vyšších
     

    Zobrazit detaily uživatele

    GET /telfa_users/user_by_id.xml?id=1
    nebo
    GET /telfa_users/user_by_login.xml?login=marek.livispace.cz

    Vrátí XML s následujícími údaji:

        <telfa-user>
          <allow-only-from-ip/>
          <available type="boolean">true</available>
          <call-to-links type="boolean">false</call-to-links>
          <can-delete-missed-calls type="boolean">true</can-delete-missed-calls>
          <created-at type="datetime">2009-03-08T22:33:59Z</created-at>
          <daily-call-cost-limit type="integer" nil="true"/>
          <email>marek@telfa.cz</email>
          <extension type="integer">10</extension>
          <id type="integer">15</id>
          <is-admin type="boolean">true</is-admin>
          <lang>cz</lang>
          <last-call-hungup-at type="datetime">2012-10-16T13:37:16Z</last-call-hungup-at>
          <login>marek.telfa.cz</login>
          <monthly-call-cost-limit type="integer" nil="true"/>
          <name>Marek Slivanský</name>
          <no-calls-abroad type="boolean">false</no-calls-abroad>
          <no-premium-calls type="boolean">false</no-premium-calls>
          <outbound-api-url/>
          <outbound-number-id type="integer">4</outbound-number-id>
          <phone-number>601234567</phone-number>
          <presence-changed-at type="datetime">2012-10-16T13:34:52Z</presence-changed-at>
          <presence-managed-manually type="boolean">true</presence-managed-manually>
          <present type="boolean">true</present>
          <sees-all-calls type="boolean">true</sees-all-calls>
          <sees-all-groups-calls type="boolean">false</sees-all-groups-calls>
          <time-zone>Prague</time-zone>
          <updated-at type="datetime">2013-08-14T17:46:31Z</updated-at>
          <user-id type="integer">95</user-id>
        </telfa-user>
    		
    vysvětlení polí >>   php příklad >>
     

    Pozn.: funkce je k dispozici pouze na serverech www2 a vyšších
     

    Přihlásit operátora

    POST /telfa_users/10/operator_log_in.xml

    Přihlásí uživatele s ID 10 a vrátí XML s detaily uživatele.

    php příklad >>
     

    Odhlásit operátora

    POST /telfa_users/10/operator_log_out.xml

    Odhlásí uživatele s ID 10 a vrátí XML s detaily uživatele.

    php příklad >>
     

    Změnit přihlášení operátora

    POST /telfa_users/change_presence.xml?login=marek.livispace.cz

    Pakliže je uživatel přihlášený, odhlásí ho. Je-li odhlášen, příhlásí ho. Vrací XML s detaily uživatele.

    php příklad >>
     

    Nastavit uživateli číslo pro odchozí hovory

    POST /telfa_users/change_outbound_number.xml

    Na tuto URL je potřeba poslat XML s následující strukturou:

        <change_outbound_number>
          <user_id>1</user_id>
          <number_id>6</number_id>
        </change_outbound_number>
    		

    Při úspěšném nastavení odchozího čísla vrátí XML s následující strukturou:

        <telfa_user type="array">
          <id>1</id>
          <name>Marek Slivanský</name>
          <outbound_number_id>6</outbound_number_id>
        </telfa_user>
    		
    php příklad >>
     

    Pozn.: funkce je k dispozici pouze na serverech www2 a vyšších
     

    Kontakty

    Výpis osobních kontaktů

    Osobní kontakty jsou individuální pro každého uživatele a nikdo jiný k nim nemá přístup.

    GET /contacts/personal.xml

    Vráti XML se seznamem osobních kontaktů

        <contacts type="array">
          <contact>
            <email>marek@livispace.cz</email>
            <id type="integer">1</id>
            <name>Marek Slivanský</name>
            <number>777123321</number>
          </contact>
        </contacts>
    		
    php příklad >>
     

    Výpis firemních kontaktů

    Firemní kontakty jsou sdílené mezi všemi uživateli pod Vaším účtem.

    GET /contacts/customer.xml

    Vráti XML se seznamem firemních kontaktů

        <contacts type="array">
          <contact>
            <email>marek@livispace.cz</email>
            <id type="integer">1</id>
            <name>Marek Slivanský</name>
            <number>777123321</number>
          </contact>
        </contacts>
    		
    php příklad >>
     

    Vytváření kontaktu

    POST /contacts.xml

    Na URL je třeba poslat XML s následující strukturou

        <contact>
          <email>marek@livispace.cz</email>
          <name>Marek Slivanský</name>
          <number>777123321</number>
          <company>777123321</company>
          <www>777123321</www>
          <note>777123321</note>
        </contact>
    		
    Pakliže přidáte parametr
    <personal>true</true>
    , vytvoří se kontakt jako osobní. V opačném případě vytvoříte firemní kontakt.
    Povinné je poslat "name" a alespoň jedno z polí "email" či "number", zbylé jsou nepovinné.

    Při úspěšném vytvoření vráti XML s detaily vytvořeného kontaktu

        <contact>
          <company>Livispace s.r.o.</company>
          <created-at type="datetime">2013-12-21T16:09:05Z</created-at>
          <email>marek@livispace.cz</email>
          <id type="integer">9</id>
          <name>Marek Slivanský</name>
          <note></note>
          <number>777123321</number>
          <personal type="boolean">false</personal>
          <telfa-user-id type="integer">742</telfa-user-id>
          <updated-at type="datetime">2013-12-21T16:09:05Z</updated-at>
          <www>www.telfa.cz</www>
        </contact>
    		
    php příklad >>


     

    Upravení kontaktu

    PUT /contacts/4.xml

    Na URL je třeba poslat XML s atributy, které se mají změnit

        <contact>
          <number>777321321</number>
        </contact>
    		

    V případě úspěšného upravení vrací prázdné tělo. Pakliže dojde k chybě, vrací XML s chybou.

    php příklad >>
     

    Smazání kontaktu

    DELETE /contacts/4.xml

    Po zavolání URL metodou DELETE dojde ke smazání kontaktu

    V případě úspěšného smazání vrací prázdné tělo. Pakliže dojde k chybě, vrací XML s chybou.

    php příklad >>
     

    SMS zprávy

    Použití SMS zpráv vyžaduje umístění SIM karet do GSM bran a aktivaci z naší strany. Pro více informací nás kontaktujte.

    Odeslání SMS zprávy

    POST /sms.xml

    Na URL je třeba poslat XML s následující strukturou

      <sms>
        <number_id>1799</number_id>
        <recipient>602123456</recipient>
        <message>Ahoj, posilam ti SMSku.</message>
      </sms>
    		
    Paramater
    number_id
    pro vaše SIM karty dohledáte pomocí API funkce Výpis čísel.

    V případě úspěšného odeslání SMS vrací prázdné tělo. Pakliže dojde k chybě, vrátí chybu.

    php příklad >>
     
    POST /sms.json

    Na URL je třeba poslat JSON s následující strukturou

      { "sms": {"number_id":"1799", "recipient":"602123456", "message":"Ahoj, posilam ti SMS."} }
    		
    Paramater
    number_id
    pro vaše SIM karty dohledáte pomocí API funkce Výpis čísel.

    V případě úspěšného odeslání vrací prázdné tělo. Pakliže dojde k chybě, vrátí chybu.

    php příklad >>
     

    Příjem SMS zpráv

    GET /sms.xml?inbound=true&from=2014-02-08+10%3A15&to=2014-02-09+10%3A35&search=ahoj&page=1
    nebo
    GET /sms.json?inbound=true&from=2014-02-08+10%3A15&to=2014-02-09+10%3A35&search=ahoj&page=1

    Načte první stránku příchozích SMS zpráv od 8.2.2014 10:15 do 9.2.2014 10:35 obsahujících řetězec "ahoj". Řetězec v search je prohledáván v číslu odesílatele, číslu příjemce a textu zprávy. Všechny parametry jsou volitelné.
    Vrací XML nebo JSON následující struktury:

          <sms type="array">
            <sm>
              <created-at type="datetime">2014-02-09T19:05:00Z</created-at>
              <id type="integer">205</id>
              <inbound type="boolean">false</inbound>
              <message>Text SMS zpravy</message>
              <number-id type="integer">1799</number-id>
              <received-at type="datetime" nil="true"></received-at>
              <recipient>602123456</recipient>
              <sender>777123456</sender>
              <telfa-user-id type="integer">1</telfa-user-id>
            </sm>
          </sms>
    		
    nebo
        { "created_at":"2014/02/09 09:43:32 +0000",
          "id":11, 
          "inbound":false, 
          "message":"ahoj, jak se mas", 
          "number_id":1799, 
          "received_at":null, 
          "recipient":"+420602123456", 
          "sender":"603603603", 
          "telfa_user_id":1 }
        
    vysvětlení polí >>   php příklad XML >>   php příklad JSON >>
     

    Mazání SMS zpráv

    DELETE /sms/201.xml
    nebo
    DELETE /sms/201.json

    Po zavolání URL metodou DELETE dojde ke smazání SMS zprávy

    V případě úspěšného smazání vrací prázdné tělo. Pakliže dojde k chybě, vrací chybu.

    php příklad XML >>   php příklad JSON >>
     

    Fronta odchozích SMS zpráv

    GET /sms/queue.xml?number_id=10
    nebo
    GET /sms/queue.json?number_id=10

    Slouží k zobrazení SMS zpráv čekajících ve frontě na odeslání. Vhodné zejména při dávkovém odesílání SMS ke kontrole, jestli je již vše odesláno před posláním další dávky.

    Data jsou načítána přímo z GSM brány, proto prosím neprovádějte tuto API akci příliš často.

    Paramater
    number_id
    pro vaše SIM karty dohledáte pomocí API funkce Výpis čísel.

    Vrací XML nebo JSON následující struktury:

          <sms-queues type="array">
            <sms-queue>
              <msg>Text SMS zpravy</msg>
              <num>601234567</num>
            </sms-queue>
          </sms-queues>
    		
    nebo
        { "msg":"ahoj, jak se mas", 
          "num":"601234567" }
        
    php příklad XML >>   php příklad JSON >>
     

    Hlášky

    Vytvoření hlášky

    POST /recordings.xml

    Na URL je třeba poslat XML s následující strukturou

      <recording>
        <name>Název</name>
        <text_to_speak>Text hlášky k vygenerování</text_to_speak>
        <voice>2</voice>
      </recording>
    		

    Parametr "voice" může mít jednu z následujících hodnot: 0 - Jan, 1 - Alena, 2 - Radka, 3 - Iva, 4 - Standa.
    Pro zpětnou kompatibilitu byl zachován parameter "female", který lze použít místo parametru "voice" a může nabývat hodnot "true" nebo "false".

    Při úspěšném vytvoření vrátí následující XML:

      <recording>
        <created-at type="datetime">2013-12-21T16:52:20Z</created-at>
        <voice type="integer">2</voice>
        <id type="integer">99</id>
        <name>Název</name>
        <text-to-speak>Text hlášky k vygenerování</text-to-speak>
      </recording>
    		
    php příklad >>
     

    Čísla a plány hovorů

    Výpis čísel, plánů hovorů a jejich kroků

    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,
            "number":"212212212",
            "number_id":10,
            "name":null,
            "id":534,
            "description":"zakaznicka linka"}]
        
    vysvětlení polí >>   php příklad >>
     
    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,
              "transfer_user_id":null,
              "action":"play",
              "menu_tries":1,
              "menu_timeout":0,
              "phone_number":null,
              "url":null,
              "run_on_days":"every_day",
              "run_after":"00:00",
              "run_before":"00:00",
              "recording_id":2722,
              "ringing_length":20,
              "sequence":1,
              "transfer_description":null,
              "continue_with_recipe_id":null,
              "id":119,
              "group_call_kind":null,
              "call_group_id":null,
              "text_to_speak":null,
              "voice": 1
            }]}
        
    vysvětlení polí >>   php příklad >>
     

    Vytváření a úprava položek plánu hovoru

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

    php příklad >>
     
    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.

    php příklad >>
     
    DELETE /recipe_items/5304.json

    Smaže položku plánu hovoru s daným ID.

    php příklad >>
     

    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í

    Webhooky

    Chcete vašim operátorům zobrazit informace o volajícím ve chvíli, kdy jím zvoní nový hovor? Nebo potřebujete mít ve vašem informačním systému okamžitý přehled o aktuálních hovorech? Lze využít tzv. webhooku, tedy vámi zadané URL, na které Telfa pošle přes HTTP POST informace při následujících událostech.

    Ve chvíli, kdy se hovor přepojuje na VoIP telefon nebo mobil uživatele, či je přes krok vytočit přepojen na externí číslo (ring_hook):

          <call>
            <hook_type>ring_hook</hook_type>
            <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>
        
    vysvětlení polí >>
     

    Podobné XML můžete dostat i ve chvíli, kdy operátor hovor zvedne (transfer_hook):

          <call>
            <hook_type>transfer_hook</hook_type>
            <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>
          
    vysvětlení polí >>
     

    Abyste byli informováni o tom, že hovor došel do kroku "zařadit do fronty skupiny" operátorů i když nebude zrovna volný žádný operátor, na kterého by se přepojilo (není tedy poslán ring_hook), pošleme vám XML group_hook:

          <call>
            <hook_type>group_hook</hook_type>
            <id>345032</id>      
            <caller_number>777123456</caller_number>
            <dialed_number>245008328</dialed_number>
            <start>2009-10-11T13:41:59+02:00</start>
            <group_start_at>2009-10-11T13:42:10+02:00</group_start_at>
            <transfer_description>Nova objednavka</transfer_description>
          </call>
          
    vysvětlení polí >>
     

    Jakmile je hovor položen, můžete dostat XML s touto informací (hangup_hook):

          <call>
            <hook_type>hangup_hook</hook_type>
            <id>345032</id>      
            <caller_number>777123456</caller_number>
            <dialed_number>245008328</dialed_number>
            <start>2009-10-11T13:41:59+02:00</start>
            <hungup_at>2009-10-11T13:42:10+02:00</hungup_at>
            <answered_by_user>jan.kubr.livispace.cz</answered_by_user>
            <transfer_description>Nova objednavka</transfer_description>
          </call>
          
    vysvětlení polí >>
     

    Webhooky se dají nastavit buď centrálně pro všechna vaše čísla (na vyžádání - zašlete nám URL) nebo pro jednotlivá čísla zvlášť přes API viz. níže.

    Pozn.: Webhooky group_hook a hangup_hook jsou k dispozici pouze na serverech www2 a vyšších.
     

    Čísla a jejich webhooky

    GET /numbers/10.json

    Vrátí detail přiděleného telefonního čísla. Funkcionalita ring_hook_url, transfer_hook_url, group_hook_url a hangup_hook_url je vysvětlena výše v části Webhooky.

            {"id":"10",
             "number":"212212212",
             "ring_hook_url":null,
             "group_hook_url":null,
             "transfer_hook_url":null,
             "hangup_hook_url":null}
    			
    php příklad >>
     
    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, transfer_hook_url, group_hook_url nebo hangup_hook_url. Pakliže chcete u kteréhokoliv z hooků zachovat původní URL, neposílejte ho. Chcete-li URL hooku vymazat, pošlete hodnotu "null" (v uvozovkách, jako string)

            "number":{"ring_hook_url":"https://moje.url.cz",
                      "transfer_hook_url": "null",
                      "group_hook_url": "null",
                      "hangup_hook_url": "https://moje.url2.cz"} 
    			
    php příklad >>
     

    Ovládání hovorů v reálném čase přes API

    Tato funkcionalita umožňuje ovládat každý hovor v reálném čase vaší aplikací s maximální jednoduchostí. Lze tak například rozpoznat volajícího podle čísla a uvítat ho jménem. Nebo je možné propojit s databází vašeho e-shopu, dohledat podle čísla zákazníka a hned zkraje hovoru ho informovat o stavu jeho nevyřízených objednávek apod.

    Princip je ten, že Telfa místo provádění předem daného plánu hovoru pokaždé zavolá URL vaší aplikace a ta pošle nazpět instrukci, co se má stát. Jakmile je akce dokončena, opět se zavolá vaše URL, a tak pořád dokola dokud se hovor neukončí. Kromě konkrétních kroků a jejich parametrů můžete posílat i libovolnou vlastní proměnnou, která je při následném volání vaší URL zaslána nazpět, což umožňuje rozpoznat průběh jednotlivých hovorů a podle toho posílat další kroky.

    Api


    V plánu hovoru krok Předat řízení:

    Api_item


    Volá URL:

    POST http://example.com/telfa_handler?caller_number=777123321&called_number=245008328&vlastni=hodnota

    Při položení hovoru přidá parameter hangup=true, tj.:

    POST http://example.com/telfa_handler?caller_number=777123321&called_number=245008328&vlastni=hodnota&hangup=true

    Proměnné jsou předávány v těle požadavku (body) v JSON formátu. Příklady použití najdete níže (pod akcemi).

    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",
                # nepovinné:
    
                "recording_id": "2",
                "ringing_length": "60",    # výchozí 20
                "outbound_number_id": "3", # ID čísla pro vytočení odchozího hovoru
              }
            

    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": "10",  # nebo
                "read": "Dobrý den, vítá Vás Telfa. Zadejte přístupový kód.",
                # nepovinné:
    
                "menu_timeout": "5",  # čekat na zadání sekund (výchozí 10)
                "max": "4",           # maximální počet zadaných číslic (výchozí neomezeno do timeoutu nebo terminátoru)
                "terminator": "#",    # zadání je možno ukončit stiskem klávesy
                "voice": "2"          # hlas řečového syntetizéru při použití read
    
    
              }
            
    Při použití kroku "menu" je potřeba nejprve hovor zvednout pomocí kroku "answer", jinak není přenos tónové volby spolehlivý. Pro specifické účely je však možné "menu" použít i bez zvednutí hovoru, s 90% telefonů funguje a je možné tak zvolit akci bez zvednutí hovoru, tedy zadarmo (např. pro ovládání domácí automatizace).
     

    Přečíst text (vyžaduje aktivovanou službu "Řečový syntetizér"):

              {
                "action": "read",
                "text_to_speak":  "Text k přečtení.",
                "voice":  "2"
              }
            

    Parametr "voice" může mít jednu z následujících hodnot: 0 - Jan, 1 - Alena, 2 - Radka, 3 - Iva, 4 - Standa.
    Pro zpětnou kompatibilitu byl zachován parameter "female", který lze použít místo parametru "voice" a může nabývat hodnot "true" nebo "false".

    Předání řízení zpět do statického plánu hovoru:

              {
                "action": "resign",
              }
            

    php příklad >>
     

    Závěr

    Pakliže Vám nějaká funkce chybí, kontaktujte nás. Telfa je od počátku vyvíjena námi, po vzájemné dohodě tak můžeme implementovat funkcionalitu dle Vašeho přání.
     
    Použití API vyžaduje aktivovanou službu "API".