Jak zacząć

        https://ssl.vpbx.pl/
                

Aby skorzystać z Callapi, w pierszym kroku należy utworzyć konto w panelu https://ssl.vpbx.pl

Po prawidłowym założeniu konta VPBX, należy wygenerować konto API, klikając na link Dostęp API -> Konta OAuth

Autentykacja

# Przykład autentykacji z wykorzystaniem cURL:
curl --header "Content-Type: application/json" \
--request POST \
--data '{"username": "valid_username", "password": "valid_password"}' \
https://api.vpbx.pl/api/v1/login
                

CallAPI / VPBX używają standardu OAuth/ JWT do autentykacji zapytań wysyłanych do platformy. Po wysłaniu poprawnego użytkownika i hasła na poniższy URL, system zwróci token JWT, który będzie używany w późniejszej komunikacji z systemem. Token należy wysyłać w każdym następnym zapytaniu w nagłówku Authorization. Proces jest opisany w rfc6749
Otrzymany token jest ważny przez czas określony w odpowiedzi, więc nie ma potrzeby generowania nowego, do czasu jego wygaśnięcia.
https://api.vpbx.pl/api/v1/login

Przykład odpowiedzi autentykacji :
{
	"result": "OK",
	"expire":"2021-08-11T15:18:53Z",
	"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAoMS0Iiwi"
}


Przykład błędnej autentykacji
{
    "error": "incorrect Username or Password",
    "result": "error"
}


        

Parametry zapytania

Pole	Typ	Opis
username	String	Nazwa użytkownika konta API.
password	String	Hasło konta API.

Odpowiedź - Pomyślna autentykacja

Pole	Typ	Opis
result	String	Status zapytania. [OK | Error]
expire	String	Data wygaśnięcia tokenu formacie RFC3339. Data w strefie czasowej UTC
token	String	Token JWT, używany do późniejszej komunikacji z API

Odpowiedź - Błędna autentykacja

Pole	Typ	Opis
result	String	Status zapytania. [OK | Error]
error	String	Opis błędu

SMS API

# Przykład autentykacji z wykorzystaniem cURL:
curl --header "Content-Type: application/json" \
--header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAoMS0Iiwi" \ 
--request POST \
--data '{"from": "callapi.pl", "to": "48500000000", "text": "To jest wiadomosc testowa.", "webhook_method": "POST", "webhook": "https://url.do.serwisu.odbierajacego"}' \
https://api.vpbx.pl/api/v1/sms
                

SMS API służy do wysyłania wiadomości SMS .
POST https://api.vpbx.pl/api/v1/sms

Przykład poprawnej odpowiedzi :
{
    "result": "OK",
    "sms_id":"7b499639-f0a4-4632-858c-8a6d913bcc90"
}


Przykład błędu
{
    "error": "token expired",
    "result": "error"
}


Przykładowy webhook (callback)
{
    "event_type": "sms-cdr",
    "sms_id": "7b499639-f0a4-4632-858c-8a6d913bcc90",
    "status": "DELIVERED",
    "parts": 1,
    "from": "callapi.pl",
    "to": "48500000000"
}


        

Parametry zapytania

Pole	Typ	Opis
from	String	Numer / nazwa nadawcy SMS.
to	String	Numer odbiorcy SMS.
webhook_method	String	Metoda wysyłania webhook [POST | GET ]. W chwili obecnej tylko metoda POST jest wspierana
webhook	String	Adres URL, na który będą wysłane statusy SMS
text	String	Treść wiadomości SMS

Odpowiedź - Pomyślne zakolejkowanie SMS

Pole	Typ	Opis
result	String	Status zapytania. [OK | Error]
sms_id	String	Unikalny identyfikator SMS w formacie UUID

Odpowiedź - odrzucenie SMS

Pole	Typ	Opis
result	String	Status zapytania. [OK | Error]
error	String	Opis błędu

Webhook (Callback)

Pole	Typ	Opis
event_type	String	Ten webhook zawsze ma wartość 'cdr-sms'
sms_id	String	UUID - taki sam jaki został zwrócony podczas wysyłania SMS
status	String	jeden z [ACCEPTED, SENT, DELIVERED, UNDELIVERED, FAILED]
parts	Int	Ilość użytych jednostkowych wiadomości SMS
from	String	Nadawca wiadomości SMS
to	String	Odbiorca wiadomości SMS

Status

Status wysyłania wiadomości SMS:

Status	Znaczenie
ACCEPTED	Wiadomość zaakceptowana do wysyłki. Status nie potwierdza wysylania wiadomości do operatora docelowego
SENT	Wiadomość wysłado do operatora. Status ten nie oznacza że wiadomość została dostarczona do odbiorcy.
DELIVERED	Wiadomość dostarczona do odbiorcy.
UNDELIVERED	Wiadomość nie została dostarczona do odbiorcy. W większości przypadków jest to status generowany przez końcowego operatora.
FAILED	Wystąpił błąd podczas wysyłania wiadomości SMS

SMS STATUS API

# Przykład autentykacji z wykorzystaniem cURL:
curl --header "Content-Type: application/json" \
--header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAoMS0Iiwi" \ 
--request GET \
https://api.vpbx.pl/api/v1/sms/7b499639-f0a4-4632-858c-8a6d913bcc90
                

STATUS SMS API służy do sprawdzania statusu, wcześniej wysłanej wiadomości SMS .
GET https://api.vpbx.pl/api/v1/sms/[sms_id]

Przykład poprawnej odpowiedzi :
{
    "parts": 1,
    "price": 0.07,
    "result": "OK",
    "sms_id": "7b499639-f0a4-4632-858c-8a6d913bcc90",
    "status": "DELIVERED"
}

Przykład błędu
{
    "error": "token expired",
    "result": "error"
}


        

Odpowiedź

Pole	Typ	Opis
result	String	Status zapytania. [OK | Error]
sms_id	String	Unikalny identyfikator SMS w formacie UUID
price	Float	Koszt wysłanej wiadomości
parts	Int	Ilość użytych jednostkowych wiadomości SMS
status	String	jeden z [ACCEPTED, SENT, DELIVERED, UNDELIVERED, FAILED]

Odpowiedź - brak statusu (błędne SMS ID)

Pole	Typ	Opis
result	String	Status zapytania. [OK | Error]
error	String	Opis błędu

SMS MO API

SMS MO API służy do odbioru SMS typu MO (Mobile Originated), czyli wysłanych z urządzenia mobilinego w kierunku API, zdefiniowagego przez użytkownika.

Przykład wiadomości wysyłanej w kierunku użytkownika końcowego, po odebrianiu SMS przez naszą platformę:
{
	"event_type": "mo-sms",
	"from": "48500123123",
	"to": "48731000000",
	"sms_id": "af787292-4def-4f0b-aa49-6b3286f237e7",
	"content_type": "UNICODE",
	"date_time": "2006-01-02 15:04:01",
	"text": "DEV To jest wysłany tekst SMS",
	"text_orig": "00440045005600200054006F0020006A006500730074002000770079007301420061006E0079002000740065006B0073007400200053004D0053",
	"keyword": "DEV",
	"udh": ""
}
        

Pola wiadomości MO SMS

Pole	Typ	Opis
event_type	String	Typ wiadomości. [mo-sms]
from	String	Nadawca wiadomości SMS
to	String	Odbiorca wiadomości SMS (Numer przypisany klientowi)
sms_id	String	Unikalny identyfikator SMS w formacie UUID
content-type	String	Kodowanie wiadomości. [ jeden z GSM7 | GSM7 | UNICODE]
date_time	String	Data / Czas odebraia wiadomości SMS
text	String	Treść wiadomości SMS w formacie Unicode
text_orig	String	Treść wiadomości SMS w formacie oryginalnym (format HEX)

Call API

Dokumentacja w przygotowaniu. Prosimy o zapoznanie się z przykładem użycia: https://github.com/vpbx-pl/examples

https://api.vpbx.pl/api/v1/callobject

{
"from": "4822100100",
"to": "TWÓJ NUMER w formacie E164, np:  48501000000",
"webhook": "http://nie.dziala.w.aplikacji.demo",
"webhook_method": "POST",
"ring_timeout": 30,
"objects": [
	{
	"type": "answer"
	},
	{
	"type": "wait",
		"params": {
		"time": 2
		}
	},
	{
	"type": "tts",
	"params": {
		"text": "Twój jednorazowy kod to: 1. 2. 3. 4.",
		"lang": "pl-PL/Maja"
		}
	},
	{
	"type": "tts",
	"params": {
		"text": "Powtarzam: Twój jednorazowy kod to: 1. 2. 3. 4.",
		"lang": "pl-PL/Maja"
		}
	}
	]
}

	    
                https://api.vpbx.pl/api/v1/callobject

	    

Parametry zapytania

Pole	Typ	Opis
from	String	Numer / nazwa nadawcy SMS.
to	String	Numer odbiorcy SMS.
webhook_method	String	Metoda wysyłania webhook [POST | GET ]. W chwili obecnej tylko metoda POST jest wspierana
webhook	String	Adres URL, na który będą wysłane statusy SMS
ring_timeout	Float	Okres oczekiwania w sekundach na odebranie telefonu
objects	[]Object	Lista objektów Call API, które wykonywane są jeden po drugim, w takiej samej kolejności, w jakiej były wysłane.

Odpowiedź - Pomyślne zakolejkowanie połączenia głosowego

Pole	Typ	Opis
result	String	Status zapytania. [OK | Error]
call_id	String	Unikalny identyfikator połączenia głosowego w formacie UUID

Odpowiedź - odrzucenie połączenia głosowego

Pole	Typ	Opis
result	String	Status zapytania. [OK | Error]
error	String	Opis błędu

Obiekty Call API

answer - odebranie połączenia po stronie API

Połączenie powinno być odebrane aby uruchomić inne obiekty, które wymagają dwukierunkowej komunikacji głosowej. Obiekt answer nie wymaga innych dodatkowych parametrów.

 

tts - Generowanie mowy

Pole	Typ	Opis
lang	String	Nazwa głosu, który będzie użyty do wygenerowania mowy. Pełna lista głosów dostępna poniżej.
text	String	Tekst do wygenerowania mowy.

 

tts_dtmf - Generowanie mowy, wybór jednocyfrowej opcji DTMF podczas mowy

Pole	Typ	Opis
lang	String	Nazwa głosu, który będzie użyty do wygenerowania mowy. Pełna lista głosów dostępna poniżej.
text	String	Tekst do wygenerowania mowy.
digits	Object	cyfry i przypisane im znaczniki

 

playfile - Odtworzenie pliku dzwiękowego

Pole	Typ	Opis
url	String	URL do pliku dzwiękowego. Wspomagane formaty to WAV i MP3.

 

playfile_dtmf - Odtworzenie pliku dźwiękowegi i wybór jednocyfrowej opcji DTMF podczas odtwarzania pliku

Pole	Typ	Opis
url	String	URL do pliku dzwiękowego. Wspomagane formaty to WAV i MP3.
digits	Object	cyfry i przypisane im znaczniki

 

dtmf - Wybór jednocyfrowej opcji DTMF

Akcja dtmf Pozwala na wprowadzenie opcji (cyfry) DTMF i wykonanie skoku do zadanego znacznika. W przypadku nie wprowadzenia żadnej cyfry, zostanie wykonana następna akcja

Pole	Typ	Opis
digits	Object	cyfry i przypisane im znaczniki

 

wait - przerwa

Pole	Typ	Opis
time	Int	czas w sekundach
text	String	Tekst do wygenerowania mowy.

 

label - znacznik

Pole	Typ	Opis
name	String	Nazwa znacznika.
text	String	Tekst do wygenerowania mowy.

 

jump - skok do zadanego znacznika

Pole	Typ	Opis
label	String	Nazwa znacznika.

 

pstn - połączenie wychodzące

Akcja ta służy do zestawienia połączenia wychodzącego. Najczęściej wykorzystwana w przypadku call-proxy lub pbx

Pole	Typ	Opis
number	String	Numer docelowy w formacie E164
ring_timeout	Float	Czas oczekiwania na odebranie połączenia.
cli	String	Numer prezentowany na połączeniu wychodzącym.

 

extension - połączenie na nume wewnętrzny

Akcja ta służy do zestawienia połączenia z numerem wewnętrznym centrali vpbx.pl. Opcja najczęściej wykorzystwana w przypadku pbx

Pole	Typ	Opis
number	String	Numer docelowy w formacie E164
ring_timeout	Float	Czas oczekiwania na odebranie połączenia.

 

hangup - zakończenie połączenia

Rozłączenia połączenia. Ta akcja nie wymaga dodatkowych parametrów

Głosy dostępne w akcjach TTS

Kod	Język / Imię
en-GB/Brian	British English / Brian
en-GB/Emma	British English / Emma
en-GB/Amy	British English / Amy
en-US/Salli	American English / Salli
en-US/Joey	American English / Joey
en-US/Chipmunk	American English / Chipmunk
en-US/Eric	American English / Eric
en-US/Ivy	American English / Ivy
en-US/Jennifer	American English / Jennifer
en-US/Justin	American English / Justin
en-US/Kandera	American English / Kandera
en-US/Kimberly	American English / Kimberly
en-GB-WLS/Gwyneth	Welsh English / Gwyneth
en-GB-WLS/Geraint	Welsh English / Geraint
en-IN/Raveena	Indian English / Raveena
en-AU/Nicole	Australian English / Nicole
en-AU/Russell	Australian English / Russell
pl-PL/Jacek	Polski / Jacek
pl-PL/Maja	Polski / Maja
pl-PL/Jan	Polski / Jan
pl-PL/Ewa	Polski / Ewa
cy-GB/Gwyneth	Welsh / Gwyneth
cy-GB/Geraint	Welsh / Geraint
da-DK/Naja	Danish / Naja
da-DK/Mads	Danish / Mads
nl-NL/Lotte	Dutch / Lotte
nl-NL/Ruben	Dutch / Ruben
fr-FR/Celine	French / Celine
fr-FR/Mathieu	French / Mathieu
fr-CA/Chantal	Canadian French / Chantal
de-DE/Marlene	German / Marlene
de-DE/Hans	German / Hans
is-IS/Dora	Icelandic / Dora
is-IS/Karl	Icelandic / Karl
it-IT/Carla	Italian / Carla
it-IT/Giorgio	Italian / Giorgio
pt-PT/Cristiano	Portuguese / Cristiano
pt-PT/Ines	Portuguese / Ines
pt-BR/Vitoria	Brazilian Portuguese / Vitoria
pt-BR/Ricardo	Brazilian Portuguese / Ricardo
ru-RU/Maxim	Russian / Maxim
ru-RU/Tatyana	Russian / Tatyana
es-ES/Conchita	Spanish / Conchita
es-ES/Enrique	Spanish / Enrique
es-US/Penelope	American Spanish / Penelope
es-US/Miguel	American Spanish / Miguel
sv-SE/Astrid	Swedish / Astrid
tr-TR/Filiz	Turkish / Filiz
nb-NO/Liv	Norwegian / Liv