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

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

    $url="https://telfa.cz/calls.xml?number=245008328";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,"<xml><nil></nil></xml>");
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    $response = curl_exec($ch);
    $info = curl_getinfo($ch); 
    curl_close ($ch);

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 >> sé

    $url="https://telfa.cz/calls/announce.xml?number=245008328&text=ahoj%20pane";
    // $url="https://telfa.cz/calls/announce.xml?number=245008328&recording_id=10";
    // $url="https://telfa.cz/calls/announce.xml?number=245008328&recipe_id=28";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,"<xml><nil></nil></xml>");
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    $response = curl_exec($ch);
    $info = curl_getinfo($ch); 
    curl_close ($ch);

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

    $url="https://telfa.cz/calls/play_recording.xml";
    $ch = curl_init();
    $data = "
            <play_recording>
              <call_id>1</call_id>
              <recording_id>6</recording_id>
              <side>both</side>
            </play_recording>
            ";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    curl_setopt($ch, CURLOPT_POSTFIELDS,$data);
    $info = curl_getinfo($ch); 
    $xml = curl_exec($ch);
    curl_close ($ch)

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

    $url="https://telfa.cz/calls/transfer_call.xml";
    $ch = curl_init();
    $data = "
            <transfer_call>
              <call_id>1</call_id>
              <continue_with_recipe_id>6</continue_with_recipe_id>
            </transfer_call>
            ";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    curl_setopt($ch, CURLOPT_POSTFIELDS,$data);
    $info = curl_getinfo($ch); 
    $xml = curl_exec($ch);
    curl_close ($ch)

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

    $url="https://telfa.cz/calls/interrupt.xml";
    $ch = curl_init();
    $data = "
            <interrupt_call>
              <id>1</id>
              <recording_id>6</recording_id>
            </interrupt_call>
            ";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    curl_setopt($ch, CURLOPT_POSTFIELDS,$data);
    $info = curl_getinfo($ch); 
    $xml = curl_exec($ch);
    curl_close ($ch)

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

    $url="https://telfa.cz/calls/current.xml?login=marek.livispace.cz";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    $info = curl_getinfo($ch); 
    $xml = curl_exec($ch);
    curl_close ($ch);

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

    // nacteni prvni stranky hovoru od 11.12.2013 10:30
    $url="https://telfa.cz/calls.xml?from=2013-12-11+10%3A30&page=1";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    $info = curl_getinfo($ch); 
    $xml = curl_exec($ch);
    curl_close ($ch);

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

    $url="https://telfa.cz/calls/1265/recording.xml";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    $info = curl_getinfo($ch); 
    $mp3 = curl_exec($ch);
    curl_close ($ch); 
    
    header("Content-Disposition: attachment; filename=call-1265.mp3");
    header("Content-type: audio/mpeg3");
    header('Content-Length: '.strlen($mp3));
    echo $mp3;

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

        $url="https://telfa.cz/telfa_users/status.xml";
        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
        $xml = curl_exec($ch);
        $info = curl_getinfo($ch); 
        curl_close ($ch);

        $url="https://telfa.cz/telfa_users/status.json";
        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json','api_key: 612e90b65911f626d4609d368c34fb69'));
        $json = curl_exec($ch);
        $info = curl_getinfo($ch); 
        curl_close ($ch);

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

    $url="https://telfa.cz/telfa_users/user_by_id.xml?id=1";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    $info = curl_getinfo($ch); 
    $xml = curl_exec($ch);
    curl_close ($ch);

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

    $url="https://telfa.cz/telfa_users/10/operator_log_in.xml";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,"<xml><nil></nil></xml>");
    $info = curl_getinfo($ch);
    $xml = curl_exec($ch);
    curl_close ($ch);

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

    $url="https://telfa.cz/telfa_users/10/operator_log_out.xml";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,"<xml><nil></nil></xml>");
    $info = curl_getinfo($ch);
    $xml = curl_exec($ch);
    curl_close ($ch);

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

    $url="https://telfa.cz/telfa_users/change_presence.xml?login=marek.livispace.cz";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,"<xml><nil></nil></xml>");
    $info = curl_getinfo($ch);
    $xml = curl_exec($ch);
    curl_close ($ch);

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

    $url="https://telfa.cz/telfa_users/change_outbound_number.xml";
    $ch = curl_init();
    $data = "
            <change_outbound_number>
              <user_id>1</user_id>
              <number_id>1792</number_id>
            </change_outbound_number>
            ";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    curl_setopt($ch, CURLOPT_POSTFIELDS,$data);
    $info = curl_getinfo($ch); 
    $xml = curl_exec($ch);
    curl_close ($ch);

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

    $url="https://telfa.cz/contacts/personal.xml";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    $info = curl_getinfo($ch);
    $xml = curl_exec($ch);
    curl_close ($ch);

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

    $url="https://telfa.cz/contacts/customer.xml";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    $info = curl_getinfo($ch);
    $xml = curl_exec($ch);
    curl_close ($ch);

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

    $data="<contact>
             <email>marek@livispace.cz</email>
             <name>Marek Slivanský</name>
             <number>777123321</number>
             <company >Livispace s.r.o.</company>
             <www>www.telfa.cz</www>
             <note></note>
           </contact>";
    $url="https://telfa.cz/contacts.xml";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,$data);
    $info = curl_getinfo($ch);
    $xml = curl_exec($ch);
    curl_close ($ch);

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

    $data="<contact>
             <number>777123456</number>
           </contact>";
    $url="https://telfa.cz/contacts/4.xml";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
    curl_setopt($ch, CURLOPT_POSTFIELDS,$data);
    $info = curl_getinfo($ch);
    $xml = curl_exec($ch);
    curl_close ($ch);

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

    $url="https://telfa.cz/contacts/4.xml";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,"<xml><nil></nil></xml>");
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
    $info = curl_getinfo($ch);
    $xml = curl_exec($ch);
    curl_close ($ch);

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

      $url="https://telfa.cz/contact_groups.xml";
      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
      $info = curl_getinfo($ch);
      $xml = curl_exec($ch);
      curl_close ($ch);

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

      $url="https://telfa.cz/contact_groups/1.xml";
      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
      $info = curl_getinfo($ch);
      $xml = curl_exec($ch);
      curl_close ($ch);

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

      $data = '<contacts type="array">
        <value>5</value>
        <value>6</value>
        <value>11</value>
        <value>25</value>
        </contacts>';
      $url="https://telfa.cz/contact_groups/1.xml";
      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
      curl_setopt($ch, CURLOPT_POST,1);
      curl_setopt($ch, CURLOPT_POSTFIELDS,$data);
      curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
      $info = curl_getinfo($ch);
      $xml = curl_exec($ch);
      curl_close ($ch);

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

    $data="<sms>
             <number_id>1799</number_id>
             <recipient>602123456</recipient>
             <message>Text SMS zpravy.</message>
           </sms>";
    $url="https://telfa.cz/sms.xml";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,$data);
    $xml = curl_exec($ch);
    $info = curl_getinfo($ch);
    curl_close ($ch);

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

    $array=array("sms" => array("number_id" => "1799", "recipient" => "602123456", "message" => "Ahoj, posilam ti SMS."));
    $data=json_encode($array);
    $url="https://telfa.cz/sms.json";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json','api_key: 612e90b65911f626d4609d368c34fb69'));
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,$data);
    $xml = curl_exec($ch);
    $info = curl_getinfo($ch);
    curl_close ($ch);

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

    $url="https://telfa.cz/sms.xml?inbound=true&from=2014-02-08+10%3A15&to=2014-02-09+23%3A15&search=ahoj&page=1";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    $xml = curl_exec($ch);
    $info = curl_getinfo($ch); 
    curl_close ($ch);

    $url="https://telfa.cz/sms.json?from=2014-02-08+10%3A15&page=1";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json','api_key: 612e90b65911f626d4609d368c34fb69'));
    $json = curl_exec($ch);
    $info = curl_getinfo($ch); 
    curl_close ($ch);

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

    $url="https://telfa.cz/sms/4.xml";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,"<xml><nil></nil></xml>");
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
    $xml = curl_exec($ch);
    $info = curl_getinfo($ch);
    curl_close ($ch);

    $url="https://telfa.cz/sms/4.json";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json','api_key: 612e90b65911f626d4609d368c34fb69'));
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,"nil");
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
    $json = curl_exec($ch);
    $info = curl_getinfo($ch);
    curl_close ($ch);

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

    $url="https://telfa.cz/sms/queue.xml?number_id=10";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    $xml = curl_exec($ch);
    $info = curl_getinfo($ch);
    curl_close ($ch);

    $url="https://telfa.cz/sms/queue.json?number_id=10";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json','api_key: 612e90b65911f626d4609d368c34fb69'));
    $json = curl_exec($ch);
    $info = curl_getinfo($ch);
    curl_close ($ch);

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

    $data="<recording>
             <name>Názov hlásenia</name>
             <text_to_speak>Text hlásenia k vygenerovaniu</text_to_speak>
             <voice>2</voice>
           </recording>";
    $url="https://telfa.cz/recordings.xml";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','api_key: 612e90b65911f626d4609d368c34fb69'));
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,$data);
    $xml = curl_exec($ch);
    $info = curl_getinfo($ch);
    curl_close ($ch);

Čí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 >>

    $repeat=1;
    $page=1;
    $json="";

    while($repeat==1){
      $ch = curl_init("https://telfa.cz/recipes.json?page=".$page);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
      curl_setopt($ch, CURLOPT_HEADER, 0);
      curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json','api_key: 612e90b65911f626d4609d368c34fb69'));
      $res = curl_exec($ch);
      $resdec=json_decode($res);
      $res= trim($res);
      if(count($resdec)>=30){
        $repeat=1;
        if($page==1){
          $json=substr($res,0,-1);
        } else {
          $json.=",".substr($res,1,-1);
        }
      } else {
        $repeat=0;
        if($page==1){
          $json=$res;
        } else {
          if(count($resdec)!=0){
            $json.=",".substr($res,1);
          } else {
            $json.="]";
          }
        }
      }
      curl_close($ch);
      $page++;
    }
    
    //teraz su v premennej $json vsetky plany hovorov

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

    $url="https://telfa.cz/recipes/7358.json";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json','api_key: 612e90b65911f626d4609d368c34fb69'));
    $info = curl_getinfo($ch); 
    $json = curl_exec($ch);
    curl_close ($ch);

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

    $item=array('recipe_item' => array('recipe_id' => 7358, 'action' => 'call', 'phone_number' => '245008328'));
    $itemjson=json_encode($item);
    $url="https://telfa.cz/recipe_items.json";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json','api_key: 612e90b65911f626d4609d368c34fb69'));
    curl_setopt($ch, CURLOPT_POSTFIELDS,$itemjson);
    $info = curl_getinfo($ch); 
    $json = curl_exec($ch);
    curl_close ($ch);

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

    $item=array('recipe_item' => array('recipe_id' => 7358, 'action' => 'call', 'phone_number' => '245008311'));
    $itemjson=json_encode($item);
    $url="https://telfa.cz/recipe_items/5304.json";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json','api_key: 612e90b65911f626d4609d368c34fb69'));
    curl_setopt($ch, CURLOPT_POSTFIELDS,$itemjson);
    $info = curl_getinfo($ch); 
    $json = curl_exec($ch);
    curl_close ($ch);

DELETE /recipe_items/5304.json

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

php príklad >>

    $url="https://telfa.cz/recipe_items/5304.json";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_POSTFIELDS,"<xml><nil></nil></xml>");
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json','api_key: 612e90b65911f626d4609d368c34fb69'));
    $info = curl_getinfo($ch); 
    $json = curl_exec($ch);
    curl_close ($ch);

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

    $url="https://telfa.cz/numbers/1792.json";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json','api_key: 612e90b65911f626d4609d368c34fb69'));
    $info = curl_getinfo($ch); 
    $json = curl_exec($ch);
    curl_close ($ch);

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

    $item=array('number' => array('ring_hook_url' => 'https://moje.url.cz', 'transfer_hook_url' => 'null', 'hangup_hook_url' => 'https://moje.url2.cz'));
    $itemjson=json_encode($item);
    $url="https://telfa.cz/numbers/10.json";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json','api_key: 612e90b65911f626d4609d368c34fb69'));
    curl_setopt($ch, CURLOPT_POSTFIELDS,$itemjson);
    $info = curl_getinfo($ch); 
    $json = curl_exec($ch);
    curl_close ($ch);

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.

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

    $body = @file_get_contents('php://input');
    $json = json_decode($body);

    // Telfa promenne
    $caller_number = $json -> caller_number;
    $called_number = $json -> called_number;
    $hangup = $json -> hangup;

    // vlastna premenna
    $pokracovanie = $json -> pokracovanie;

    if( empty($hangup) ){
      if( empty($pokracovanie) ){
        $a = array( 'action' => 'play', 'recording_id' => '25', 'pokracovanie' => '1' );
      } elseif( $pokracovanie == 1 ){
        $a = array( 'action' => 'call', 'number' => '777123321', 'ringing_length' => '30', 'pokracovanie' => '2' );
      } elseif( $pokracovanie == 2 ){
        $a = array( 'action' => 'resign' );  
      }
    } else {
      $a = array( 'action' => 'hangup' );
    }

    echo json_encode($a);

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