Spis treści

CloudPBX API

Dokumentacja interfejsu systemu CloudPBX

Wersja 1.1

System CloudPBX udostępnia zestaw narzędzi do prostego zarządzania wirtualną centralą telefoniczną poprzez aplikacje webowe. W szczególnych przypadkach istnieje potrzeba integracji systemu telekomunikacyjnego z systemem informatycznym klienta w zakresie pobierania danych połączeń telefonicznych. Funkcjonalność taką umożliwia udostępnione publiczne API CloudPBX oparte o interfejsy REST/WebSocket

1. Komunikacja REST

Interface API w zakresie pobierania danych oparty jest o specyfikację REST, protokół HTTPS i format JSON. Wymiana komunikacji odbywa się w szyfrowanym kanale SSL protokołu HTTP.

Adresy interface CloudPBX:

https://api.cloudpbx.pl, https://api2.cloudpbx.pl

1.1 Autoryzacja

Autoryzacja i autentykacja odbywa się za pomocą klucza API, przekazywanego przez dostawcę usługi. Klucz musi zostać umieszczony w nagłówku HTTP 

Authorization: Bearer [AUTHKEY]

1.2 cdr

Polecenie cdr pozwala na pobranie listy rekordów billingowych za dany okres. Do pobrania danych wykorzystywana jest metoda GET.

Przykład wywołania CURL: 

curl -X GET -H 'Authorization: Bearer [APIKEY]' https://api.cloudpbx.pl/cdr

Standardowo wywołanie zwraca listę rekordów billingowych w bieżącym dniu. Aby zmienić zakres dat należy podać parametry 'datestart' i 'datestop' w formacie „YYYY-MM-DD” 

curl -X GET -H 'Authorization: Bearer [APIKEY]' https://api.cloudpbx.pl/cdr?datestart=2021-10-01&datestop=2021-10-07

Polecenie zwraca tablicę z listą rekordów w formacie JSON: 

[
  {
    "calldate":"2021-12-15 11:25:02",
    "clid":"\"Sekretariat 3\" <101>",
    "src":"101",
    "dst":"105",
    "channel":"SIP\/PBX-101-00000028",
    "dstchannel":"SIP\/PBX-105-00000029",
    "lastapp":"Queue",
    "duration":13,
    "billsec":13,
    "disposition":"ANSWERED",
    "uniqueid":"1639563902.75",
    "cost":"",
    "zone":""
  }
]

Pola rekordu:

Uwaga! metoda pozwala na pobranie maksymalnie 10 000 rekordów CDR

1.3 record

Polecenie record pozwala na pobranie listy nagrań w danym okresie lub konkretnego nagrania do zapisu na dysku lokalnym. Do pobrania danych wykorzystywana jest metoda GET. 

curl -X GET -H 'Authorization: Bearer [APIKEY]' https://api.cloudpbx.pl/record

Wywołanie polecenia bez parametrów powoduje zwrócenie listy nagrań w formacie JSON. Domyślnie polecenie zwraca nagrania z bieżącego dnia. Aby zmienić zakres dat należy podać parametry 'datestart' i 'datestop' w formacie „YYYY-MM-DD” 

curl -X GET -H 'Authorization: Bearer [APIKEY]' https://api.cloudpbx.pl/record?datestart=2021-10-01&datestop=2021-10-07

Polecenie zwraca tablicę obiektów JSON: 

[
  {
    "uniqueid":"1552558647.371",
    "src":"101",
    "dst":"105",
    "format":"wav",
    "date":"2019-03-14 11:17:28"
  }
]

Pola struktury:

Uwaga! polecenie pozwala na pobranie listy maksymalnie 5000 nagrań

Pobranie nagrania: 

curl -X GET --output record.wav -H 'Authorization: Bearer [APIKEY]' https://api.cloudpbx.pl/record/[uniqueid]

Wywołanie polecenia record z podaniem identyfkatora powoduje pobranie nagrania. W przypadku CURL warto dodać opcję –output pozwalająca na zapis danych do pliku.

1.4 dial

Polecenie dial pozwala na wywołanie połączenia pomiędzy abonentem A i abonentem B. Do wykonania połączenia wykorzystywana jest metoda GET.

Polecenie wymagapodania parametrów

Przykład wywołania CURL: 

curl -X GET -H 'Authorization: Bearer [APIKEY]' https://api.cloudpbx.pl/dial?cpa=101&cpb=200

Wywołanie polecenia dial zwraca

1.5 sendSMS

Polecenie dostępne jedynie w przypadku, gdy centrala ma udostępnioną bramkę SMS. Aby aktywować usługę należy skontaktować się z biurem obsługi klienta CloudPBX.

Polecenie sendSMS pozwala na wysłanie wiadomości tekstowej do sieci GSM poprzez bramkę SMS. Do wysłania wykorzystana jest metoda POST, w której należy podać paramerty wadomości:

UWAGA! maksymalna długość wiadomości wynosi 1024 znaki.

Przykład wywołania CURL: 

curl -v -X POST -H 'Authorization: Bearer [APIKEY]'\
 -d "to"="[GSMNUMBER]"\
 -d "body"="tekst wysyłanej wiadomości"\
 -d "test"="true"\
   https://api.cloudpbx.pl/sendSMS

Gdzie:

Wywołanie polecenia zwraca

Gdzie: RESPONSE to obiekt w formacie json. Przykładowe wartości obiektu RESPONSE: 

{"responseId":"3421756012963258480","responseStatus":"QUEUE","responseErrorMesage":null}

Wartość pola responseId określa unikalny numer identyfikacyjny wiadomości, dzięki temu pozwala na monitorowanie stanu wysyłki wiadomości. Aktualny stan przesyłany jest kanałem zwrotnym komunikacją WS Po zmianie stanu, w kanale WS przesyłany jest komunikat smsSendResponse zawierający aktualne informacje o wysyłce.

Wartości pola responseStatus opisane są w punkcie 2.3.5 (smsSendResponse).

Pole responseErrorMesage zawiera wiadomość błędu jeśli taki wystąpił. Wartość null oznacza poprawne wykonanie komendy oraz przekazanie wiadomości SMS do wysyłki.

Dodatkowo responseId zapisywane jest w rekordzie CDR w polu uniqueid.Dzięki temu można odszukać rekord cdr zawierający parametry taryfikacyjne w tabeli billingów.

2. Komunikacja WebSocket

Interface WebSocket jest mechanizmem działającym odmiennie od REST. O ile REST zwraca odpowiedzi na zadane pytania, o tyle WebSocket strumieniuje zdarzenia do klienta. Po podłączeniu klienta do WebSocket, na bieżąco przesyłane są komunikaty o zmianie stanów centrali i urządzeń. Dzięki temu kient może na bieżąco reagować na przychodzące zdażenia.

Protokół WebSocket opiera się częściowo na standardzie HTTP, wykorzystując nagłówek UPGRADE, który powoduje otwarcie kanału komunikacyjnego, którym przesyłane są komunikaty z serwera. WebSocket wspierany jest przez współczesne przeglądarki i JS. Nie brakuje również bibliotek w wielu językach programowania pozwalających łatwo zaimplementować obsługę WS.

Najprostsza imlementacja może opierać się na aplikacji curl lub websocat (https://github.com/vi/websocat). Podłączenie do websocketu umożliwia podgląd przychodzących komunikatów.

Cześć języków zawierających wbudowaną obsługę protokołu HTTP umożliwia wykorzystanie WS poprzez odpowiednią konstrukcję nagłówka HTTP oraz wykorzystanie metody UPGRADE. Niektóre języki (JS, C#) posiadają wbudowane biblioteki wspomagające obsługę WS, inne oferują zewnętzne biblioteki:

2.1 Nawiązanie połączenia WS

Do nawiązania połączenia z api CloudPBX niezbędne jest posiadanie adresu serwera API, nazwy centrali oraz klucza autoryzacyjnego. Te dane pozwolą na zbudowanie prawidłowego URL: 

[PROTO]://[SERVER]/ws/pbx_[PBX_NAME]?pbxkey=[APIKEY]

gdzie:

Przykładowe podłączenie do WebSocket za pomocą CURL: 

curl --include \
     --no-buffer \
     --output - \
     --header "Connection: Upgrade" \
     --header "Upgrade: websocket" \
     --header "Host: pbxvisor1.cloudpbx.pl" \
     --header "Origin: https://pbxvisor1.cloudpbx.pl" \
     --header "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
     --header "Sec-WebSocket-Version: 13" \
     https://pbxvisor1.cloudpbx.pl/ws/pbx_MojaCentrala?pbxkey=MyExampleKey

Przykładowe połączenie za pomocą aplikacji websocat 

websocat  https://pbxvisor1.cloudpbx.pl/ws/pbx_MojaCentrala?pbxkey=MyExampleKey

2.2 Komunikaty centrali

Po podłączeniu do portu WebSocket w momencie wystąpienia zdarzenia na centrali zostaje wygenerowany event. Eventy podawane są w formacje JSON w poniższym formacie: 

{"id":386,"channel":"pbx_MojaCentrala","text":{data}}

gdzie

Przychodzący komunikat zawiera jeden lub więcej eventów zawierających dodatkowe informacje dotyczące każdego zdarzenia.

2.3 Opis eventów

2.3.1 subscriber

{
"subscriber":
    {
    "peer":"MojaCentrala-101",
    "statusValue":1 
    }
}

Event subscriber opisuje stan konta abonenckiego (peera). opis parametrów eventu:

2.3.2 extstatus

{
"extstatus":
    {  
    "exten":"130",
    "status":4
    }
}

Event extstatus opisuje stan aparatu. Często jest on równoznaczny ze stanem eventu subscriber, opis parametrów eventu:

2.3.3 queue

{
"queue":
    {
    "peer":"Kolejka1",
    "calls":"1"
    }
}

Event queue opisuje zmianę stanu w kolejce. Gdy w danej kolejce zmienia się liczba oczekujących połączeń, ich ilość raportowana jest za pomocą tego zdarzenia.

2.3.4 qmember

{
"qmember":
    {
    "peer":"MojaCentrala-101",
    "queue":"Kolejka1",
    "m_status":"1",
    "m_ct":"0",
    "m_mbshp":"static",
    "m_paused":"0",
    "m_name":"Agent 1",
    "m_location":"SIP\/MojaCentrala-101"
    }
}

Event qmember generowany jest w przypadku zmiany stanu agenta obsługującego kolejkę

2.3.5 cmember

{
"cmember":
    {
    "channel":"SIP\/MojaCentrala-101-0005f005",
    "action":"add",
    "conference":"SesjaRady",
    "callerIDName":"Jan Nowak",
    "callerIDNum":"101"
    }
}

Event cmember opisuje zmianę stanu uczestnika pokoju konferencyjnego

2.3.5 smsSendResponse

{
"smsSendResponse": 
     {
     "MsgId": "3292468348841377230",
     "to": "48XXXXXXXXX",
     "status": "SENT"
     }     
}

Event smsSendResponse przesyłany jest w momencie zmiany stanu zadania wiadomości SMS wysłanej do sieci komórkowej za pomocą bramki cloudPBX.

Możliwe raportowane stany

2.4 Wartości stanów

Pole statusValue eventu subscriber przyjmuje wartości liczbowe określające stan konta abonenckiego:

Pole m_status eventu qmember przyjmuje wartości liczbowe określające stan agenta:

3. Przykładowy kod kliencki

W celu testów i własnej implementacji, pod adresem https://github.com/grzegorziwaniec/cloudpbx_api_client został udostępniony przykładowy kod klienta w języku PHP. Kod prezentuje metody autoryzacji oraz sposób wykorzystania dostępnych metod API zarówno protokołu REST jaki WebSocket