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

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/BrianBritish English / Brian
en-GB/EmmaBritish English / Emma
en-GB/AmyBritish English / Amy
en-US/SalliAmerican English / Salli
en-US/JoeyAmerican English / Joey
en-US/ChipmunkAmerican English / Chipmunk
en-US/EricAmerican English / Eric
en-US/IvyAmerican English / Ivy
en-US/JenniferAmerican English / Jennifer
en-US/JustinAmerican English / Justin
en-US/KanderaAmerican English / Kandera
en-US/KimberlyAmerican English / Kimberly
en-GB-WLS/GwynethWelsh English / Gwyneth
en-GB-WLS/GeraintWelsh English / Geraint
en-IN/RaveenaIndian English / Raveena
en-AU/NicoleAustralian English / Nicole
en-AU/RussellAustralian English / Russell
pl-PL/JacekPolski / Jacek
pl-PL/MajaPolski / Maja
pl-PL/JanPolski / Jan
pl-PL/EwaPolski / Ewa
cy-GB/GwynethWelsh / Gwyneth
cy-GB/GeraintWelsh / Geraint
da-DK/NajaDanish / Naja
da-DK/MadsDanish / Mads
nl-NL/LotteDutch / Lotte
nl-NL/RubenDutch / Ruben
fr-FR/CelineFrench / Celine
fr-FR/MathieuFrench / Mathieu
fr-CA/ChantalCanadian French / Chantal
de-DE/MarleneGerman / Marlene
de-DE/HansGerman / Hans
is-IS/DoraIcelandic / Dora
is-IS/KarlIcelandic / Karl
it-IT/CarlaItalian / Carla
it-IT/GiorgioItalian / Giorgio
pt-PT/CristianoPortuguese / Cristiano
pt-PT/InesPortuguese / Ines
pt-BR/VitoriaBrazilian Portuguese / Vitoria
pt-BR/RicardoBrazilian Portuguese / Ricardo
ru-RU/MaximRussian / Maxim
ru-RU/TatyanaRussian / Tatyana
es-ES/ConchitaSpanish / Conchita
es-ES/EnriqueSpanish / Enrique
es-US/PenelopeAmerican Spanish / Penelope
es-US/MiguelAmerican Spanish / Miguel
sv-SE/AstridSwedish / Astrid
tr-TR/FilizTurkish / Filiz
nb-NO/LivNorwegian / Liv