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

Obecné

Ověřování probíhá pomocí HTTP Basic, použijte váš libovolný administrátorský účet. Vždy je třeba nastavit Accept header na application/xml nebo přidat .xml za URL (případně ekvivalent pro JSON), viz příklady.

XML REST API

Click to call

POST http://telfa.cz/calls.xml?number=245008328

Vytočí Telfa účet uživatele, pod kterým je URL zavoláno a spojí hovor s číslem předaným jako parametr. Je-li Telfa účet nedostupný, použije se nastavený mobilní telefon uživatele.

Zavolej a přečti text

POST http://telfa.cz/calls/announce.xml?number=245008328&text=ahoj%20kamo

Vytočí zadané telefonní číslo a přečte volanému zadaný text pomocí řečového sytentizéru (text2speech).

Aktuálně probíhající hovor

GET http://telfa.cz/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, obdobné jako v případě webhooku výše:

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

Seznam všech hovorů

GET http://telfa.cz/calls.xml?from=2009-10-11+10%3A30

Vrátí XML obsahující všechny hovory od 11.10.2009 10:30. Možno využít například pro notifikace o zmeškaných hovorech:

      <calls type="array">
        <call>
          <answered_at/>
          <answered_by_user_id/>
          <bridge_start_at>2009-10-11T13:42:19+02:0</bridge_start_at>
          <caller_number>777123456</caller_number>
          <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/>
          <transfer_description>Nova objednavka</transfer_description>
          <transferred_to_number/>
          <voice_mail_file_name/>
          <recording_file_name>/calls/13110/recording</recording_file_name>
        </call>
      </calls>
      

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 http://telfa.cz/calls.xml?from=2009-10-11+10%3A30&page=15

Pokud vrátí prázdnou stránku:

        <nil-classes type="array"/>
      

Webhook

Chcete vašim operátorům zobrazit informace o volajícím ve chvíli, kdy jím zvoní nový hovor? Požádejte nás o nastavení tzv. webhooku, tedy URL, na které Telfa pošle přes HTTP POST informace o právě zvonícím hovoru:

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

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

      <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>
        <answered_by_login>jan.kubr.livispace.cz</answered_by_login>
        <transfer_description>Nova objednavka</transfer_description>
      </call>
      

Pokud si chcete tyto informace od serveru vyžádat sami, je to možné, viz předchozí sekce.

Úplné ovládání ústředny přes API

V plánu hovoru:

Volá URL:

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

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

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

Akce

Jako odpověď na výše uvedený dotaz je třeba poslat JSON s akcí, která se má vykonat. Po skončení akce je výše uvedené URL zavoláno znovu (s výjimkou akce Položit).

Zvednout:

          {
            "action": "answer"
          }    
        

Položit:

          {
            "action": "hangup"
          }    
        

Přehrát:

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

Přepojit:

          {
            "action": "transfer",
            buď:
            "transfer_user_login": "jan.kubr.livispace.cz",
            nebo:
            "transfer_user_id": "2",
            #nepovinne:
            "recording_id": "2",
            "transfer_description": "Fakturace",
            "ringing_length": "60",
          }
        

Vytočit:

          {
            "action": "call",
            "number": "777123321",
            #nepovinne:
            "recording_id": "2",
            "ringing_length": "60",
          }
        

Nahrát zprávu:

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

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

Výběr:

          {
            "action": "menu",
            "recording_id": => "4",
            #nepovinne:
            "menu_timeout": "10",
            "max": "1",
            "terminator": "#"
          }
        

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

          {
            "action": "resign",
          }
        

Závěr

Dokumentace API nemusí být úplná, pokud vám něco chybí, kontaktujte nás. Funkce webhook a plná kontrola vyžadují aktivaci z naší strany.