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

Hovory

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

  • stav uživatelů
  • informace o uživateli
  • historie přihlašování operátorů
  • přihlášení/odhlášení operátorů
  • nastavení čísla pro odchozí hovory
  • výpis skupin uživatelů
  • výpis uživatelů ze skupiny uživatelů
  • Kontakty

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

  • odeslání SMS zprávy
  • stažení SMS zpráv
  • mazání SMS zpráv
  • fronta SMS zpráv
  • Hlášky

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

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

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

  • popis realtime ovládání
  • akce a jejich použití
  • API pro odchozí hovory
  • 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 >>

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


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

    POST /calls/play_recording.xml

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

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

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


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

    POST /calls/transfer_call.xml

    Přepojí probíhající hovor na zaslané ID opakující se části, kterou předem vytoříte přes webové rozhraní v sekci Plán hovoru, 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 >>


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


    Ukončení hovoru

    POST /calls/interrupt.xml

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

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

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

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

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

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

    Vrátí XML s informacemi o právě probíhajícím hovoru uživatele s daným loginem:

            <call>
              <caller_number>777123456</caller_number>
              <dialed_number>245008328</dialed_number>
              <start>2009-10-11T13:41:59+02:00</start>
              <answered_at>2009-10-11T13:42:10+02:00</answered_at>
              <transfer_description>Nova objednavka</transfer_description>
            </call>
            
    vysvětlení polí >>   php příklad >>


    Seznamy hovorů

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

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

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

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

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

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

    Odhlásit operátora

    POST /telfa_users/10/operator_log_out.xml

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

    php příklad >>
     

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

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

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

    php příklad >>
     

    Nastavit uživateli číslo pro odchozí hovory

    POST /telfa_users/change_outbound_number.xml

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

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

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

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

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

    Kontakty

    Výpis osobních kontaktů

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

    GET /contacts/personal.xml

    Vráti XML se seznamem osobních kontaktů

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

    Výpis firemních kontaktů

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

    GET /contacts/customer.xml

    Vráti XML se seznamem firemních kontaktů

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

    Vytváření kontaktu

    POST /contacts.xml

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

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

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

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


     

    Upravení kontaktu

    PUT /contacts/4.xml

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

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

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

    php příklad >>
     

    Smazání kontaktu

    DELETE /contacts/4.xml

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

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

    php příklad >>

    Výpis skupin kontaktů

    GET /contact_groups.xml
    nebo
    GET /contact_groups.json

    Vráti XML se seznamem skupin kontaktů

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

    php příklad >>

    Výpis kontaktů ze skupiny kontaktů

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

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

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

    php příklad >>

    Aktualizace skupiny kontaktů

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

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

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

    php příklad >>

     

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

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

    Hlášky

    Vytvoření hlášky

    POST /recordings.xml

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

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

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

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

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

    Čísla a plány hovorů

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

    GET /recipes.json

    Vrátí JSON s plány hovorů pro přidělená čísla. Plány jsou stránkovány po 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 >>
     
    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 >>
     

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

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

    POST /recipe_items.json

    Založí novou položku plánu hovoru a umístí jí na jeho konec. Vrací buď 200 OK a v těle JSON s daty položky nebo 422 Unprocessable Entity a v těle seznam chyb. V těle požadavku musí být minimálně:

    "recipe_item":{
                "recipe_id":534, // ID plánu hovoru, do kterého se má položka zařadit
                "action":"play"// Název akce, kterou bude položka provádět, seznam akcí níže
                } 
          

    Dále zde mohou být libovolné další položky, které jsou vidět výše ve výpisu detailu plánu hovoru v položce "items".

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

    Aktualizuje položku plánu hovoru s daným ID. Tělo požadavku vypadá obdobně, jako v případě vytváření položky.

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

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

    php příklad >>
     

    Seznam možných akcí položek plánů hovorů

    Kód akce Popis
    play Přehrát
    read Přečíst
    menu Výběr
    transfer Přepojit na VoIP telefon
    transfer_to_mobile Přepojit na mobilní telefon
    transfer_to_group Zařadit do fronty skupiny
    call Vytočit
    voice_mail Nahrát zprávu
    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 >>
     
    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 >>
     

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

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

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

    Api


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

    Api_item


    Volá URL:

    POST http://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 >>

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


     

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

    # tady zacina anglicka verze