Možnosti integrace telefonní ústředny Telfa s vašimi systémy

Obecné

Ověřování probíhá pomocí API klíče:
U libovolného uživatele si v Telfě vygenerujte API klíč pro ostatní systémy. U API requestů poté vložte do požadavku proměnnou "api_key", a to buď do HTTP hlavičky "api_key" (nejbezpečnější - používáme v příkladech níže), jako GET parametr do URL (https://telfa.cz/calls.xml?api_key=612e90b65911f626d4609d368c34fb69), nebo pro metody POST/PUT/DELETE jako proměnnou "api_key" do JSON/XML požadavku.

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://www5.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.

Integrace

Raynet

WPJ e-shop

Dent21

ISP Admin

Microsoft Dynamics

REST API - funkce po skupinách

Závěr

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

Click to call

POST /calls.xml?number=245008328[&method=both][&telfa_user_id=1][&auto_answer=true]

nebo

POST /calls.xml?number=245008328[&method=both][&telfa_user_login=marek.telfa.cz][&auto_answer=true]

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.
Volitelně je možné přidat parametr telfa_user_id či telfa_user_login (pakliže se autorizujete uživatelem, který je administrátor) a vytočení proběhne uživateli, kterého specifikujete.
Použijete-li parametr

auto_answer=true

, hovor se na VoIP telefonu uživatele automaticky zodpoví a ihned dojde k vytáčení čísla předaného jako parametr (vyžaduje podporu Auto Answer pomocí SIP header na straně VoIP telefonu).
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 >>

    $url="https://www5.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 - zavolej a proveď akci

POST /calls/announce.xml?number=245008328&text=ahoj%20pane[&voice=2]

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í. Volitelně je možné použít parametr voice, který určuje hlas řečového syntetizéru. Parametr "voice" může mít jednu z následujících hodnot: 0 - Jan, 1 - Alena, 2 - Radka, 3 - Iva, 4 - Standa.
Pro použití varianty s recipe_id je potřebné mít aktivovánu službu Automatická volání.

php příklad >>

    $url="https://www5.telfa.cz/calls/announce.xml?number=245008328&text=ahoj%20pane";
    // $url="https://www5.telfa.cz/calls/announce.xml?number=245008328&recording_id=10";
    // $url="https://www5.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);

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

    $url="https://www5.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)

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, nebo přes API.
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 >>

    $url="https://www5.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)

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

POST /calls/monitor.xml?call_id=1

nebo

POST /calls/monitor.json?call_id=1

Spustí příposlech hovoru - vytočí VoIP telefon uživatele, kterým se API request autorizuje a spustí příposlech hovoru.
Ve výchozím stavu příjemce příposlechu pouze poslouchá a do hovoru nevstupuje. Pomocí tónové volby je však možné toto při příposlechu ovlivnit:
   - stiskem 2 je možné hovořit s volajícím
   - stiskem 1 s volaným
   - stiskem 3 s oběma najednou

Na tuto URL je potřeba prázdné XML (nebo JSON):

      <xml>
        <nil></nil>
      </xml>

php příklad XML >>

    $url="https://www5.telfa.cz/calls/monitor.xml?call_id=1";
    $ch = curl_init();
    $data = "
        <xml>
          <nil>1</nil>
        </xml>
        ";
    $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č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 >>

    $url="https://www5.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 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 >>

    $url="https://www5.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);

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

Výpis všech hovorů se specifikací počtu záznamů na stránku (max. 2000)

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

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

    // nacteni prvni stranky hovoru od 11.12.2013 10:30
    $url="https://www5.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 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/1265/recording.xml

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

php příklad >>

    $url="https://www5.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)); # při výskytu chyby pod PHP 7.4 vypusťte tento řádek
    echo $mp3;

Stažení hlasové zprávy

GET calls/1251/voice_mail.xml

Vrátí hlasovou zprávu, kterou lze uložit nebo nabídnout ke stažení ve vlastní aplikaci.

php příklad >>

    $url="https://www5.telfa.cz/calls/1251/voice_mail.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=voice_mail-1251.mp3");
    header("Content-type: audio/mpeg3");
    header('Content-Length: '.strlen($mp3)); # při výskytu chyby pod PHP 7.4 vypusťte tento řádek
    echo $mp3;

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

        $url="https://www5.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://www5.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);

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

nebo

GET /telfa_users/user_by_id.json?id=1

nebo

GET /telfa_users/user_by_login.json?login=marek.livispace.cz

Vrátí XML/JSON 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 >>

    $url="https://www5.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);

Historie přihlašování uživatele

GET /telfa_users/<id uživatele>/presence_history.xml?from=2018-04-01&to=2018-04-30

nebo

GET /telfa_users/<id uživatele>/presence_history.json?from=2018-04-01&to=2018-04-30

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

    $url="https://www5.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á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 >>

    $url="https://www5.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);

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

    $url="https://www5.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);

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>

API funkce na výpis čísel a jejich number_id naleznete zde.

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

        $url="https://www5.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);

Výpis skupin uživatelů

GET /call_groups.xml

nebo

GET /call_groups.json

Vráti XML se seznamem skupin uživatelů

      <call-groups type="array">
        <call-group>
          <id type="integer">1</id>
          <name>Operátoři</name>
          <average-call-length type="integer">321</average-call-length>
          <created-at type="datetime">2020-06-12T08:04:28Z</created-at>
          <updated-at type="datetime">2020-06-12T08:04:28Z</updated-at>
        </call-group>
      </call-groups>

nebo JSON

      { "id":1,
        "name":"Operátoři",
        "average_call_length":321,
        "created_at":"2020/06/12 08:04:28 +0000",
        "updated_at":"2020/06/12 08:04:28 +0000" 
      }

php příklad >>

      $url="https://www5.telfa.cz/call_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 uživatelů ze skupiny uživatelů

GET /call_groups/1.xml

nebo

GET /call_groups/1.json

Vráti XML s detailem skupiny uživatelů a se seznamem uživatelů do ní zařazených

      <call-group>
        <id type="integer">1</id>
        <name>Operátoři</name>
        <average-call-length type="integer">321</average-call-length>
        <created-at type="datetime">2020-06-12T08:04:28Z</created-at>
        <updated-at type="datetime">2020-06-12T08:04:28Z</updated-at>
        <call-groups-telfa-users type="array">
          <call-groups-telfa-user>
            <telfa-user-id type="integer">2</telfa-user-id>
            <name>Marek Slivanský</name>
            <sequence type="integer">1</sequence>
            <mobile type="boolean">false</mobile>
          </call-groups-telfa-user>
        </call-groups-telfa-users>
      </call-group>

nebo JSON

      { "id":1,
        "name":"Operátoři",
        "average_call_length":null,
        "created_at":"2020/06/12 08:04:28 +0000",
        "updated_at":"2020/06/12 08:04:28 +0000",
        "call_groups_telfa_users":[
          { "telfa_user_id":2,
            "name":"Marek Slivanský"
            "mobile":false,
            "sequence":1
          }
        ]
      }

php příklad >>

      $url="https://www5.telfa.cz/call_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);

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

    $url="https://www5.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 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 >>

    $url="https://www5.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ář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 >>

    $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://www5.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);

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

    $data="<contact>
             <number>777123456</number>
           </contact>";
    $url="https://www5.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);

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

    $url="https://www5.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://www5.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://www5.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://www5.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 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>

Parametr

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í XML s chybou (kód chyby v

error_code

, textový popis chyby v

error_text

).

php příklad >>

    $data="<sms>
             <number_id>1799</number_id>
             <recipient>602123456</recipient>
             <message>Text SMS zpravy.</message>
           </sms>";
    $url="https://www5.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 třeba poslat JSON s následující strukturou

    { "sms": {"number_id":"1799", "recipient":"602123456", "message":"Ahoj, posilam ti SMS."} }

Parametr

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í JSON s chybou (kód chyby v

error_code

, textový popis chyby v

error_text

).

php příklad >>

    $array=array("sms" => array("number_id" => "1799", "recipient" => "602123456", "message" => "Ahoj, posilam ti SMS."));
    $data=json_encode($array);
    $url="https://www5.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);

Možné chybové stavy:
400 - INVALID_RECIPIENT - nevalidní číslo příjemce
413 - TOO_LONG - příliš dlouhá SMS zpráva
500 - OTHER_ERROR - jiná chyba
550 - SEND_LIMIT_EXCEEDED_OR_SIM_NOT_REGISTERED - překročen měsíční limit počtu odeslaných SMS nebo SIM není zaregistrována
900 - GATEWAY_ERROR - chyba při přenosu SMS na GSM bránu
901 - EMPTY_RECIPIENT - prázdný příjemce
902 - INCORRECT_NUMBER_ID - nesprávné ID čísla, přes které se SMS posílá

Stažení SMS zpráv

Stáhnout si můžete pouze přijaté, pouze odeslané anebo oboje SMS dohromady, řazené podle data vytvoření SMS v Telfě. U odeslaných SMS můžete navíc sledovat stav odeslání a doručení cílovému příjemci.
Pro okamžitý příjem SMS zpráv bez nutnosti příliš častého periodického načítání doporučujeme použít SMS webhook.

GET /sms.xml

nebo

GET /sms.json

GET parametry, které můžete u XML i JSON requestů použít, všechny jsou volitelné:

inbound

- je-li nastaveno na true, vrátí se pouze přijaté SMS, nastaveno na false, vrátí pouze odeslané SMS, není li posláno vůbec, vrátí přijaté i odeslané SMS dohromady

from

- datum a čas odkdy se mají SMS načítat, v url encoded formátu YYYY-MM-DD HH:MM, tedy např. 2014-02-08+10%3A15

to

- datum a čas dokdy se mají SMS načítat, v url encoded formátu YYYY-MM-DD HH:MM, tedy např. 2020-02-09+10%3A35

page

- výpisy jsou ve výchozím nastavení stránkovány po 200 záznamech na stránku. 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ž 200 záznamy nebo stránka prázdná.

per_page

- nastaví jiný počet záznamů na stránku, maximum je 2000

search

- vrátit jen zprávy obsahující tento string v čísle odesílatele, čísle příjemce či v textu zprávy

Příklad použití - stažení přijatých i odeslaných SMS

GET /sms.xml?from=2014-02-08+10%3A15&to=2020-02-09+10%3A35&search=ahoj&page=1&per_page=500

nebo

GET /sms.json?from=2014-02-08+10%3A15&to=2020-02-09+10%3A35&search=ahoj&page=1&per_page=500

Načte první stránku příchozích SMS zpráv od 8.2.2014 10:15 do 9.2.2020 10:35 obsahujících řetězec "ahoj".
Vrací XML nebo JSON následující struktury:

        <sms type="array">
          <sm>
            <created-at type="datetime">2014-02-09T19:05:00Z</created-at>
            <encoding>unicode</encoding>
            <id type="integer">205</id>
            <inbound type="boolean">false</inbound>
            <last-sent-time type="datetime" nil="true"></last-sent-time>
            <message>Ahoj, jak se máš?</message>
            <number-id type="integer">1799</number-id>
            <received-at type="datetime" nil="true"></received-at>
            <recipient>602123456</recipient>
            <reply-to-sms-id type="integer" nil="true"/>
            <retries type="integer" nil="true"/>
            <sender>777123456</sender>
            <status type="integer">3</status>
            <telfa-user-id type="integer">1</telfa-user-id>
            <text-status>DELIVERED</text-status>
          </sm>
        </sms>

nebo

      { "created_at":"2014/02/09 09:43:32 +0000",
        "encoding":"unicode", 
        "id":11, 
        "inbound":false, 
        "last_sent_time":null, 
        "message":"Ahoj, jak se máš?", 
        "number_id":1799, 
        "received_at":null, 
        "recipient":"+420602123456", 
        "reply_to_sms_id":null, 
        "retries":null, 
        "sender":"603603603", 
        "status":3, 
        "telfa_user_id":1,
        "text_status":"DELIVERED" }

vysvětlení polí >> php příklad XML >> php příklad JSON >>

    $url="https://www5.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://www5.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);

Možné stavy odeslaných SMS zpráv:

1 - WAITING - zpráva uložena v Telfě a předává se na GSM bránu
202 - SENDING - zpráva předána na GSM bránu a odesílá se
2 - SENT - zpráva odeslána
3 - DELIVERED - zpráva doručena na cílový telefon
4 - SENT_FAIL - chyba odeslání zprávy - opakované odmítnutí mobilním operátorem (např. není akceptováno číslo příjemce nebo došlo k blokaci odchozích služeb ze strany mobilního operátora)
400 - INVALID_RECIPIENT - nevalidní číslo příjemce
413 - TOO_LONG - příliš dlouhá SMS zpráva
500 - OTHER_ERROR - jiná chyba
550 - SEND_LIMIT_EXCEEDED_OR_SIM_NOT_REGISTERED - překročen měsíční limit počtu odeslaných SMS nebo SIM není zaregistrována
900 - GATEWAY_ERROR - chyba při přenosu SMS na GSM bránu
901 - EMPTY_RECIPIENT - prázdný příjemce
902 - INCORRECT_NUMBER_ID - nesprávné ID čísla, přes které se SMS posílá

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

    $url="https://www5.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://www5.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 odchozích SMS zpráv

API funkce pro fronty odchozích zpráv se používají pouze u staršího typu námi používaných GSM bran, které neumožňovaly detailní sledování stavu doručení. U nových GSM bran lze stav odeslání sledovat detailně pro každou SMS zprávu pomocí výše uvedené dokumentace na stažení SMS.

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

    $url="https://www5.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://www5.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áš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 >>

    $data="<recording>
             <name>Název hlášky</name>
             <text_to_speak>Text hlášky k vygenerování</text_to_speak>
             <voice>2</voice>
           </recording>";
    $url="https://www5.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 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 30ti 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ž 30ti záznamy nebo stránka prázdná.

        [{"contact_group_id":null,
          "number":"212212212",
          "number_id":10,
          "name":null,
          "gsm_gateway":false,
          "id":534,
          "description":"zakaznicka linka"}]

vysvětlení polí >> php příklad >>

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

    while($repeat==1){
      $ch = curl_init("https://www5.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)>=20){
        $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++;
    }
    
    //nyni jsou v promenne $json vsechny plany hovoru

GET /recipes/534.json

Vrátí detail plánu hovoru.

        {"number":"245008328",
         "number_id":10,
         "contact_group_id":null,
         "name":null,
         "id":534,
         "items":
          [{"remove_from_queue_after":null,
            "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,
            "menu_items":[]
            "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 >>

    $url="https://www5.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áření plánů hovorů

POST /recipes.json

Založí nový plán hovoru. Vrací buď 200 OK a v těle JSON s ID plánu hovoru nebo 422 Unprocessable Entity a v těle seznam chyb. V těle požadavku stačí uvést název plánu hovoru:

"recipe":{
           "name":"Můj plán hovoru",
         }

php příklad >>

    $recipe=array('recipe' => array('name' => 'Můj plán hovoru'));
    $recipejson=json_encode($recipe);
    $url="https://www5.telfa.cz/recipes.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,$recipejson);
    $info = curl_getinfo($ch); 
    $json = curl_exec($ch);
    curl_close ($ch);

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

    $item=array('recipe_item' => array('recipe_id' => 7358, 'action' => 'call', 'phone_number' => '245008328'));
    $itemjson=json_encode($item);
    $url="https://www5.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. Tělo požadavku vypadá obdobně, jako v případě vytváření položky.

php příklad >>

    $item=array('recipe_item' => array('recipe_id' => 7358, 'action' => 'call', 'phone_number' => '245008311'));
    $itemjson=json_encode($item);
    $url="https://www5.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

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

php příklad >>

    $url="https://www5.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);

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
transfer_to_last_caller	Přepojit dle historie
api	Předat řízení
mobility_extension	Spojit s číslem
continue_with	Pokračuj opakující se částí
reply_with_sms	Odpověz SMS zprávou
send_sms	Pošli SMS
send_email	Pošli e-mail
extension_user	Spojit na zadanou linku uživatele
extension_group	Spojit na zadanou linku skupiny
record_call	Nahrávat hovor

U kroku Výběr je možné použít parametr "menu_items_count", kterým se určí počet voleb k vygenerování. V odpovědi na request poté obdržíte seznam recipe_id pro jednotlivé volby.

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.

V okamžiku, kdy vznikne příchozí hovor v Telfě (incoming_hook):

        <call>
          <hook_type>incoming_hook</hook_type>
          <id>11677</id>      
          <caller_number>777123456</caller_number>
          <dialed_number>245008328</dialed_number>
          <start>2009-10-11T13:41:59+02:00</start>
        </call>

vysvětlení polí >>

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

Při vytočení odchozího hovoru Vám pošleme následující XML (outgoing_hook):

        <call>
          <hook_type>outgoing_hook</hook_type>
          <id>345032</id>      
          <caller_number>marek.telfa.cz</caller_number>
          <dialed_number>777123456</dialed_number>
          <start>2017-10-11T13:41:59+02:00</start>
        </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>
          <group_start_at>2009-10-11T13:42:02+02:00</group_start_at>
          <ring_start_at>2009-10-11T13:42:03+02:00</ring_start_at>
          <answered_at>2009-10-11T13:42:05+02:00</answered_at>
          <answered_by_user>jan.kubr.livispace.cz</answered_by_user>
          <transfer_description>Nova objednavka</transfer_description>
        </call>

vysvětlení polí >>

Používáte-li náš SIM hosting, může se Vám hodit webhook, který na zadanou URL předává přijaté SMS v JSON formátu (sms_hook):

        {"id":1410972,
         "number_id":"857",
         "sender":"+420608608608",
         "sender_name":null,
         "recipient":"+420602602602",
         "received_at":"2022-09-07 23:09:29",
         "message":"Dobrý večer, jak se máte?"}

vysvětlení polí >>

Webhooky se dají nastavit přes API pro jednotlivá čísla dle popisu zde.

Čísla a jejich webhooky

Seznam přidělených čísel a jejich ID naleznete zde.

GET /numbers/10.json

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

          {"id":"10",
           "number":"212212212",
           "incoming_hook_url":null,
           "group_hook_url":null,
           "ring_hook_url":null,
           "transfer_hook_url":null,
           "outgoing_hook_url":null,
           "hangup_hook_url":null,
           "sms_hook_url":null}

php příklad >>

    $url="https://www5.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. 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 incoming_hook_url, group_hook_url, ring_hook_url, transfer_hook_url, outgoing_hook_url, hangup_hook_url a sms_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). Webhooky je možné posílat na více URL najednou, stačí je oddělit čárkou.

          "number":{"incoming_hook_url":"https://moje.url.cz,https://backup.url.cz",
                    "group_hook_url":"https://moje.url.cz",
                    "ring_hook_url":"https://moje.url.cz",
                    "transfer_hook_url": "null",
                    "outgoing_hook_url": "null",
                    "hangup_hook_url": "https://moje.url2.cz",
                    "sms_hook_url": "null"}

php pří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://www5.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á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.

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

Api_item

Volá URL:

POST http://telfa.local/telfa_test?caller_number=777123321&called_number=245008328&vlastni=hodnota

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

POST http://telfa.local/telfa_test?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 (podporováno i v API pro odchozí hovory):

            {
              "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",
              "auto_pick_up": "true"    # automaticky zvednout hovor (ověřena podpora pouze u Cisco telefonů)
            }

Vytočit (podporováno i v API pro odchozí hovory):

            {
              "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 (podporováno i v API pro odchozí hovory):

            {
              "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") (podporováno i v API pro odchozí hovory):

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

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

    // vlastni promenna
    $pokracovani = $json -> pokracovani;

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

    echo json_encode($a);

API pro odchozí hovory

URL pro ovládání odchozích hovorů se nastavuje u každého uživatele, jako parametr "API URL pro odchozí hovory". Pakliže není URL vyplněna, odchozí hovory probíhají běžným způsobem. Funkce je obdobná jako výše uvedené ovládání příchozích hovorů v reálném čase. Příklady použití najdete výše (sekce Akce). V odchozích hovorech je však podporována pouze část akcí (popsáno u jednotlivých akcí). Můžete využít např. pro nastavení odchozího čísla pro konkrétní odchozí hovor, přehrání hlášky operátorovi před spojením hovoru apod.

Volá "API URL pro odchozí hovory" zadanou u uživatele, např.:

POST http://telfa.local/telfa_test?caller_number=marek.telfa.cz&called_number=245008328&vlastni=hodnota

Proměnné jsou předávané v těle požadavku (body) v JSON formátu.

předávané parametry >> php příklad >>

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

      
   if($json -> done == 1){
      $a = array ("action" => "call", "number" => $json -> called_number, "outbound_number_id" => 1805);
    } else {
      $a = array ("action" => "read", "text_to_speak" => "Nastavuji odchozí číslo.", "done" => 1);
    }

echo json_encode($a);

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