Možnosti integrácie telefónnej ústredne Telfa s Vašimi systémami

Všeobecné

Overovanie prebieha pomocou HTTP Basic, použite váš ľubovoľný administrátorský účet. Ako užívateľské meno sa používa email užívateľa so @ (oproti formátu s bodkou v VoIP telefónoch). Vždy je nutné nastaviť správnu hodnotu hlavičky Content-Type, v prípade XML na „application/xml", v prípade JSON „application/json".
Základné URL závisí od umiestnenia vášho účtu. Na tomto serveri je to https://telfa.cz. Adresa môže byť takisto napr. https://www4.telfa.sk nebo https://www2.telfa.sk atd. Pozrite sa, kam ste presmerovaní po prihlásení do webového rozhrania, rovnaké URL sa používa aj pre API.
Za túto základnú URL pridajte príslušnú cestu, viď ďalej v dokumentácii.
 

REST API - funkcie po skupinách

Hovory

  • vytočenie hovoru
  • automatické hovory – zavolaj a vykonaj akciu
  • prehraj hlásenie do hovoru
  • prepojenie hovoru
  • ukončenie hovoru
  • výpisy hovorov a stiahnutie nahrávok
  • Užívatelia

  • stav užívateľov
  • informácie o užívateľovi
  • prihlásenie/odhlásenie operátorov
  • nastavenie čísla pre odchádzajúce hovory
  • Kontakty

  • výpis kontaktov
  • vytvorenie, upravenie a mazanie kontaktov
  • výpis skupin kontaktů
  • výpis kontaktů ze skupiny kontaktů
  • aktualizace skupiny kontaktů
  • SMS správy

  • odoslanie SMS správy
  • príjem SMS správ
  • mazanie SMS správ
  • front SMS správ
  • Hlásenia

  • vygenerovanie hlásenia z textu pomocou Text To Speech
  • Čísla a plány hovorov

  • výpis čísel, plánov hovorov a ich krokov
  • vytváranie a úprava položiek plánu hovoru
  • Webhooky

  • typy webhookov a ich opis
  • nastavenie webhookov
  • Ovládanie hovorov v reálnom čase

  • popis realtime ovládania
  • akcie a ich použitie
  • Záver


     

    Vytváranie a ukončovanie hovorov

    Click to call

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

    Vytočí VoIP telefón alebo mobil užívateľa, pod ktorým sa autorizujete pri volaní URL, a spojí hovor s číslom odovzdaným ako parameter. Parameter „method" je voliteľný a jeho možné hodnoty sú nasledujúce:

  • prázdny alebo neuvedený – najprv sa vytočí VoIP telefón užívateľa a pokiaľ je nedostupný, vytočí sa mobil užívateľa
  • voip
    vytočí sa VoIP telefón užívateľa, ak je nedostupný, nič sa ďalej nedeje
  • mobile
    vytočí sa mobil užívateľa, ak je nedostupný, nič sa ďalej nedeje
  • both
    vytočí zároveň VoIP telefón aj mobil užívateľa, vyhráva ten hovor, ktorý je skôr zdvihnutý
  • php príklad >>

    Automatické hovory – zavolaj a vykonaj akciu

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

    Vytočí zadané telefónne číslo a prečíta volanému zadaný text pomocou rečového sytentizéru (text musí byť URL encoded), prehrá zadanú hlášku alebo pokračuje vopred pripravenú Opakujúcu sa časť.

    php príklad >>


    Prehranie hlásenia do prebiehajúceho hovoru

    POST /calls/play_recording.xml

    Prehrá hlásenie do prebiehajúceho hovoru, zmixuje ju so zvukom hovoru, ten sa teda nepreruší. Voliteľne prehrá iba volajúcemu alebo iba volanému. API request skončí ihneď, nečaká sa na dokončenie prehrávania hlásenia.

    Na túto URL je potrebné poslať XML s nasledujúcou štruktúrou (parameter side je voliteľný a môže nadobúdať hodnoty "both" – prehrať obom stranám (predvolené), "caller" – prehrať iba volajúcemu, "called" – prehrať iba volanému):

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


    Prepojenie prebiehajúceho hovoru

    POST /calls/transfer_call.xml

    Prepojí prebiehajúci hovor na zaslané ID opakujúcej sa časti, ktorú vopred vytvoríte cez webové rozhranie v sekcii Plán hovoru, alebo pres API.
    Ak hovor aktuálne vyzváňa operátorovi na telefóne alebo je už spojený, k prepojeniu dôjde až po položení hovoru alebo timeoutu vyzváňania.
    V ostatných prípadoch dôjde k prepájaniu okamžite (pri čakaní vo fronte, prehrávaní hlásenia, nahrávania hlasovej správy).

    Na túto URL je potrebné poslať XML s nasledujúcou štruktúrou:

          <transfer_call>
            <call_id>1</call_id>
            <continue_with_recipe_id>6</continue_with_recipe_id>
          </transfer_call>
          
    php príklad >>


    Ukončenie hovoru

    POST /calls/interrupt.xml

    Preruší hovor, voliteľne prehrá hlásenie (ak je zadané) a potom hovor ukončí.

    Na túto URL je potrebné poslať XML s nasledujúcou štruktúrou (parameter recording_id je voliteľný):

          <interrupt_call>
            <id>1</id>
            <recording_id>6</recording_id>
          </interrupt_call>
          
    php príklad >>

    Výpis hovorov a stiahnutie nahrávok

    Aktuálne prebiehajúci hovor užívateľa

    GET /calls/current.xml?login=jan.kubr.livispace.cz

    Vráti XML s informáciami o práve prebiehajúcom hovore užívateľa s daným loginom:

            <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>
            
    vysvetlenie polí >>   php príklad >>


    Zoznamy hovorov

    Aktuálne prebiehajúce hovory
    GET /calls/all_current.xml
    Výpis všetkých hovorov
    GET /calls.xml?from=2013-12-11+10%3A30

    Vráti XML obsahujúci všetky hovory, ktoré začali alebo boli položené od 11.12.2013 10:30.
    Možno využiť napríklad pre notifikácie o zmeškaných hovoroch. Pri pravidelnom načítaní, prosím, zvážte, či nesťahujete zbytočne veľké obdobie.

            <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>
            
    vysvetlenie polí >>   způsoby využití >>   php príklad >>
     
    Hovory sú vždy stránkované po 20 záznamoch, pre vrátenie všetkých strán navyšujte parameter page do tej doby, než sa vám vráti stránka s menej ako 20 záznamami alebo stránka prázdna:

    GET /calls.xml?from=2013-12-11+10%3A30&page=3

    Kým nevráti prázdnu stránku:

              <nil-classes type="array"/>
            

    Pre načítanie detailu iba jedného hovoru pomocou jeho ID použite:

    GET /calls.xml?id=3

    Tieto dáta možno získať aj vo formáte 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}]
    vysvetlenie polí >>
     

    Stiahnutie nahrávky hovoru

    GET calls/1265/recording.xml

    Vráti nahrávku hovoru, ktorú možno uložiť alebo ponúknuť na stiahnutie vo vlastnej aplikácii.

    php príklad >>
     

    Informácie o užívateľoch a ich nastaveniach

    Zobraziť zoznam užívateľov a ich stav

    GET /telfa_users/status.xml
    alebo
    GET /telfa_users/status.json

    Vypíše zoznam všetkých užívateľov, pokiaľ sú prihlásení alebo odhlásení a odkedy, a tiež, či sú dostupní pre príjem hovorov, alebo sú práve obsadení hovorom.
    Vracia XML alebo JSON nasledujúcej štruktúry:

            <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>
          
    alebo
          { "present":true,
            "name":"Marek Livispace",
            "presence_changed_at":"2014/06/16 23:41:08 +0000",
            "available":true,
            "id":744,
            "email":"marek@livispace.cz" }
          
    vysvetlenie polí >>   php príklad XML >>   php príklad JSON >>
     

    Zobraziť detaily užívateľa

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

    Vráti XML s nasledujúcimi údajmi:

          <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>
          
    vysvetlenie polí >>   php príklad >>

    Prihlásiť operátora

    POST /telfa_users/10/operator_log_in.xml

    Prihlási užívateľa s ID 10 a vráti XML s detailmi užívateľa.

    php príklad >>
     

    Odhlásiť operátora

    POST /telfa_users/10/operator_log_out.xml

    Odhlási užívateľa s ID 10 a vráti XML s detailmi užívateľa.

    php príklad >>
     

    Zmeniť prihlásenie operátora

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

    Ak je používateľ prihlásený, odhlási ho. Ak je odhlásený, prihlási ho. Vracia XML s detailmi užívateľa.

    php príklad >>
     

    Nastaviť užívateľovi číslo pre odchádzajúce hovory

    POST /telfa_users/change_outbound_number.xml

    Na túto URL je potrebné poslať XML s nasledujúcou štruktúrou:

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

    Pri úspešnom nastavení odchádzajúceho čísla vráti XML s nasledujúcou štruktúrou:

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

    Kontakty

    Výpis osobných kontaktov

    Osobné kontakty sú individuálne pre každého užívateľa a nikto iný k nim nemá prístup.

    GET /contacts/personal.xml

    Vrátí XML so zoznamom osobných kontaktov

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

    Výpis firemných kontaktov

    Firemné kontakty sú zdieľané medzi všetkými užívateľmi pod Vaším účtom.

    GET /contacts/customer.xml

    Vrátí XML so zoznamom firemných kontaktov

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

    Vytváranie kontaktu

    POST /contacts.xml

    Na URL je potrebné poslať XML s nasledujúcou štruktúrou

          <contact>
            <email>marek@livispace.cz</email>
            <name>Marek Slivanský</name>
            <number>777123321</number>
            <company>Livispace</company>
            <www></www>
            <note></note>
          </contact>
          
    Keď mu pridáte parameter
    <personal>true</true>
    , vytvorí sa kontakt ako osobný. V opačnom prípade vytvoríte firemný kontakt.
    Povinné je poslať "name" a aspoň jedno z polí "email" či "number", zvyšné sú nepovinné.

    Pri úspešnom vytvorení vráti XML s detailmi vytvorené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 príklad >>


     

    Upravenie kontaktu

    PUT /contacts/4.xml

    Na URL je potrebné poslať XML s atribútmi, ktoré sa majú zmeniť

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

    V prípade úspešného upravenia vracia prázdne telo. Pokiaľ dôjde k chybe, vracia XML s chybou.

    php príklad >>
     

    Zmazanie kontaktu

    DELETE /contacts/4.xml

    Po zavolaní URL metódou DELETE dôjde k zmazaniu kontaktu

    V prípade úspešného zmazania vracia prázdne telo. Pokiaľ dôjde k chybe, vracia XML s chybou.

    php príklad >>

    Výpis skupin kontaktů

    GET /contact_groups.xml
    nebo
    GET /contact_groups.json

    Vráti XML se seznamem skupin kontaktů

          <contact-groups type="array">
            <contact-group>
              <id type="integer">1</id>
              <name>VIP klienti</name>
            </contact-group>
          </contact-groups>
          
    nebo JSON
          { "name":"VIP klienti",
            "id":1 }
          

    php příklad >>

    Výpis kontaktů ze skupiny kontaktů

    GET /contact_groups/1.xml
    nebo
    GET /contact_groups/1.json

    Vráti XML se seznamem kontaktů zařazených do skupiny kontaktů

          <contacts type="array">
            <contact>
              <company type="integer">Livispace s.r.o.</company>
              <email>info@telfa.cz</email>
              <id>2</id>
              <name>Marek Slivanský</name>
              <number>609111646</number>
            </contact>
          </contacts>
          
    nebo JSON
          { "company":"Livispace s.r.o.",
            "email":"info@telfa.cz",
            "id":"2",
            "name":"Marek Slivanský",
            "number":"609111646",
          }
          

    php příklad >>

    Aktualizace skupiny kontaktů

    Při aktualizaci skupiny kontaktů se smaže původní obsah a nahradí se ID kontaktů, které byly zaslány
    PUT /contact_groups/1.xml

    Číslo v URL je ID skupiny kontaktů, kterou chceme aktualizovat. Na adresu je třeba poslat XML s ID kontaktů

          <contacts type="array">
            <value>2</value>
            <value>8</value>
            <value>14</value>
          </contacts>
          
    Pakliže některé ze zaslaných ID kontaktů neexistuje, nejsou přidány do skupiny. Ostatní (existující) jsou však i tak přidány a odpověď je i tak poslána 200 OK (chyba se vrátí jen v případě neexistující skupiny kontaktů).

    php příklad >>

     

    SMS správy

    Použitie SMS správ vyžaduje umiestnenie SIM kariet do GSM brán a aktiváciu z našej strany. Pre viac informácií nás kontaktujte.

    Odoslanie SMS správy

    POST /sms.xml

    Na URL je potrebné poslať XML s nasledujúcou štruktúrou

        <sms>
          <number_id>1799</number_id>
          <recipient>602123456</recipient>
          <message>Ahoj, posilam ti SMSku.</message>
        </sms>
          
    Parameter
    number_id
    pre vaše SIM karty dohľadáte pomocou API funkcie Výpis čísel.

    V prípade úspešného odoslania SMS vracia prázdne telo. Pokiaľ dôjde k chybe, vráti chybu.

    php príklad >>
     
    POST /sms.json

    Na URL je potrebné poslať JSON s nasledujúcou štruktúrou

        { "sms": {"number_id":"1799", "recipient":"602123456", "message":"Ahoj, posilam ti SMS."} }
          
    Parameter
    number_id
    pre vaše SIM karty dohľadáte pomocou API funkcie Výpis čísel.

    V prípade úspešného odoslania vracia prázdne telo. Pokiaľ dôjde k chybe, vráti chybu.

    php príklad >>
     

    Príjem SMS správ

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

    Načíta prvú stránku prichádzajúcich SMS správ od 8.2.2014 10:15 do 9.2.2014 10:35 obsahujúcich reťazec "ahoj". Reťazec v search je prehľadávaný v čísle odosielateľa, čísle príjemcu a v texte správy. Všetky parametre sú voliteľné.
    Vracia XML alebo JSON nasledujúcej štruktúry:

            <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>
          
    alebo
          { "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 }
          
    vysvetlenie polí >>   php príklad XML >>   php príklad JSON >>
     

    Mazanie SMS správ

    DELETE /sms/201.xml
    alebo
    DELETE /sms/201.json

    Po zavolaní URL metódou DELETE dôjde k zmazaniu SMS správy

    V prípade úspešného zmazania vracia prázdne telo. Pokiaľ dôjde k chybe, vracia chybu.

    php príklad XML >>   php príklad JSON >>
     

    Fronta odchádzajúcich SMS správ

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

    Slúži na zobrazenie SMS správ čakajúcich v rade na odoslanie. Vhodné najmä pri dávkovom odosielaní SMS na kontrolu, či je už všetko odoslané pred poslaním ďalšej dávky.

    Dáta sú načítané priamo z GSM brány, preto, prosím, nerobte túto API akciu príliš často.

    Parameter
    number_id
    pre vaše SIM karty dohľadáte pomocou API funkcie Výpis čísel.

    Vracia XML alebo JSON nasledujúce štruktúry:

            <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 príklad XML >>   php príklad JSON >>
     

    Hlásenia

    Vytvorenie hlásenia

    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>
          

    Parameter "voice" môže mať jednu z nasledujúcich hodnôt: 0 - Jan (CZ), 1 - Alena (CZ), 2 - Radka (CZ), 3 - Iva (CZ), 4 - Standa (CZ), 5 - Jiří (CZ), 6 - Melanie (SK), 7 - Olga (RU).

    Pri úspešnom vytvorení vráti nasledujúce 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ázov</name>
          <text-to-speak>Text hlásenia k vygenerovaniu</text-to-speak>
        </recording>
          
    php príklad >>
     

    Čísla a plány hovorov

    Výpis čísel, plánov hovorov a ich krokov

    GET /recipes.json

    Vráti JSON s plánmi hovorov pre pridelené čísla. Plány sú stránkované po 20 záznamoch. Pre vrátenie všetkých strán navyšujte parameter page do tej doby, než sa vám vráti stránka s menej ako 20 záznamami alebo stránka prázdna.

              [{"contact_group_id":null,
              "number":"212212212",
              "number_id":10,
              "name":null,
              "id":534,
              "description":"zakaznicka linka"}]
          
    vysvetlenie polí >>   php príklad >>
     
    GET /recipes/534.json

    Vráti 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
              }]}
          
    vysvetlenie polí >>   php príklad >>
     

    Vytváranie a úprava položiek plánu hovoru

    POST /recipe_items.json

    Založí novú položku plánu hovoru a umiestni ju na jeho koniec. Vracia buď 200 OK a v tele JSON s dátami položky alebo 422 Unprocessable Entity a v tele zoznam chýb. V tele požiadavky musí byť minimálne:

    "recipe_item":{
                "recipe_id":534, // ID plánu hovoru, do kterého sa má položka zaradiť
                "action":"play"// Názov akcie, ktorú bude položka vykonávať, zoznam akcií nižšie
                } 
          

    Ďalej tu môžu byť ľubovoľné ďalšie položky, ktoré sú vidieť vyššie vo výpise detailu plánu hovoru v položke "items".

    php príklad >>
     
    PUT /recipe_items/5304.json

    Aktualizuje položku plánu hovoru s daným ID. Telo požiadavky vyzerá obdobne ako v prípade vytvárania položky.

    php príklad >>
     
    DELETE /recipe_items/5304.json

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

    php príklad >>
     

    Zoznam možných akcií položiek plánov hovorov

    Kód akcie Popis
    play Prehrať
    read Prečítať
    menu Výber
    transfer Prepojiť na VoIP telefón
    transfer_to_mobile Prepojiť na mobilný telefón
    transfer_to_group Zaradiť do fronty skupiny
    call Vytočiť
    voice_mail Nahrať správu
    transfer_to_last_caller Prepojiť podľa historie
    api Odovzdať riadenie
    mobility_extension Spojiť s číslom
    continue_with Pokračuj opakujúcou sa časťou
    reply_with_sms Odpovedz SMS správou
    send_sms sk, recipes, actions, send_sms
    send_email Pošli e-mail
    extension_user Spojiť na zadanú linku uživatelia
    extension_group Spojiť na zadanú linku skupiny
    record_call Nahrávať hovor

    Webhooky

    Chcete vašim operátorom zobraziť informácie o volajúcom vo chvíli, keď im zvoní nový hovor? Alebo potrebujete mať vo vašom informačnom systéme okamžitý prehľad o aktuálnych hovoroch? Možno využiť tzv. webhooku, teda vami zadané URL, na ktoré Telfa pošle cez HTTP POST informácie pri nasledujúcich udalostiach.

    Vo chvíli, keď sa hovor prepája na VoIP telefón alebo mobil užívateľa, alebo je cez krok vytočiť prepojený 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>
          
    vysvetlenie polí >>
     

    Podobné XML môžete dostať aj vo chvíli, keď operátor hovor zdvihne (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>
            
    vysvetlenie polí >>
     

    Aby ste boli informovaní o tom, že hovor došiel do kroku "zaradiť do frontu skupiny" operátorov, aj keď nebude práve voľný žiadny operátor, na ktorého by sa prepojilo (nie je teda poslaný 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>
            
    vysvetlenie polí >>
     

    Akonáhle je hovor položený, môžete dostať XML s touto informáciou (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>
            
    vysvetlenie polí >>
     

    Webhooky sa dajú nastaviť buď centrálne pre všetky vaše čísla (na vyžiadanie – zašlite nám URL), alebo pre jednotlivé čísla osobitne cez API viď. nižšie.

    Čísla a ich webhooky

    GET /numbers/10.json

    Vráti detail prideleného telefónneho čísla. Funkcionalita ring_hook_url, transfer_hook_url, group_hook_url a hangup_hook_url je vysvetlená vyššie v časti Webhooky.

              {"id":"10",
               "number":"212212212",
               "ring_hook_url":null,
               "group_hook_url":null,
               "transfer_hook_url":null,
               "hangup_hook_url":null}
            
    php príklad >>
     
    PUT /numbers/10.json

    Aktualizuje číslo. Vracia buď 200 OK a v tele JSON s dátami čísla alebo 422 Unprocessable Entity a v tele zoznam chýb. Meniť možno len ring_hook_url, transfer_hook_url, group_hook_url alebo hangup_hook_url. Pokiaľ chcete u ktoréhokoľvek z Hook zachovať pôvodné URL, neposielajte ho. Ak chcete URL hook vymazať, pošlite hodnotu "null" (v úvodzovkách ako 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 príklad >>
     

    Ovládanie hovorov v reálnom čase cez API

    Táto funkcionalita umožňuje ovládať každý hovor v reálnom čase vašej aplikácie s maximálnou jednoduchosťou. Možno tak napríklad rozpoznať volajúceho podľa čísla a privítať ho menom. Alebo je možné prepojiť s databázou vášho e-shopu, dohľadať podľa čísla zákazníka a hneď skraja hovoru ho informovať o stave jeho nevybavených objednávok apod.

    Princíp je ten, že Telfa miesto vykonávania vopred daného plánu hovoru zakaždým zavolá URL vašej aplikácie a tá pošle naspäť inštrukciu, čo sa má stať. Akonáhle je akcia dokončená, opäť sa zavolá vaša URL, a tak stále dokola, kým sa hovor neukončí. Okrem konkrétnych krokov a ich parametrov môžete posielať aj ľubovoľnú vlastnú premennú, ktorá je pri následnom volaní vašej URL zaslaná naspäť, čo umožňuje rozpoznať priebeh jednotlivých hovorov a podľa toho posielať ďalšie kroky.

    Api


    V pláne hovoru krok Odovzdať riadenie:

    Api_item


    Volá URL:

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

    Pri položení hovoru pridá parameter hangup=true, tj.:

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

    Premenné sú odovzdávané v tele požiadavky (body) v JSON formáte. Príklady použitia nájdete nižšie (pod akciami).

    Akcie

    Ako odpoveď na vyššie uvedený požiadavek, je potrebné poslať JSON s akciou, ktorá sa má vykonať. Po skončení akcie je vyššie uvedené URL zavolané znova (s výnimkou akcie Položiť).

    Zdvihnúť:

                {
                  "action": "answer"
                }    
              

    Položiť:

                {
                  "action": "hangup"
                }    
              

    Prehrať:

                {
                  "action": "play",
                  "recording_id": "4"
                }
              

    Prepojiť:

                {
                  "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",    # predvolené 20
                  "outbound_number_id": "3", # ID čísla pre vytočenie odchádzajúceho hovoru
                }
              

    Nahrať správu:

                {
                  "action": "voice_mail",
                  "call_group_id": "2",
                }
              

                {
                  "action": "voice_mail",
                  "flempo_team_id": "12",
                }
              

    Výber:

                {
                  "action": "menu",
                  "recording_id": "10",  # alebo
                  "read": "Dobrý deň, víta Vás Telfa. Zadajte prístupový kód.",
                  # nepovinné:
    
                  "menu_timeout": "5",  # čakať na zadanie sekúnd (predvolené 10)
                  "max": "4",           # maximálny počet zadaných číslic (predvolené neobmedzene do timeoutu alebo terminátora)
                  "terminator": "#",    # zadanie je možné ukončiť stlačením klávesy
                  "voice": "7"          # hlas rečového syntetizátora pri použití read  
    
    
                }
              
    Pri použití kroku "menu" je potrebné najprv hovor zdvihnúť pomocou kroku "answer", inak nie je prenos tónovej voľby spoľahlivý. Pre špecifické účely je však možné "menu" použiť aj bez zdvihnutia hovoru, s 90 % telefónov funguje a je možné tak zvoliť akciu bez zdvihnutia hovoru, teda zadarmo (napr. pre ovládanie domácej automatizácie).
     

    Prečítať text (vyžaduje aktivovanú službu "Rečový syntetizér"):

                {
                  "action": "read",
                  "text_to_speak":  "na prečítanie.",
                  "voice":  "7"
                }
              

    Parameter "voice" môže mať jednu z nasledujúcich hodnôt: 0 - Jan (CZ), 1 - Alena (CZ), 2 - Radka (CZ), 3 - Iva (CZ), 4 - Standa (CZ), 5 - Jiří (CZ), 6 - Melanie (SK), 7 - Olga (RU).

    Odovzdanie riadenia späť do statického plánu hovoru:

                {
                  "action": "resign",
                }
              

    php príklad >>
     

    Záver

    Pokiaľ Vám nejaká funkcia chýba, kontaktujte nás. Telfa je od začiatku vyvíjaná nami, takže po vzájomnej dohode môžeme implementovať funkcionalitu podľa Vášho želania.
     
    Použitie API vyžaduje aktivovanú službu "API".