Specyfikacja

SENDLY SMS API

Specyfikacja v1.2

SENDLY SMS API działa na zasadzie przesyłania komunikatów za pomocą protokołu HTTP. Do obsługi wiadomości SMS dostępne są dwa wzajemnie wykluczające się tryby: SMS API oraz 3CX API

1. SMS API

1.1 Wysyłka wiadomości

Jest to domyślny tryb działania API, przeznaczony do wykorzystania z aplikacjami obsługującymi REST API. Do wysyłki SMS udostępniany jest następujący endpoint:

POST https://api.sendly.link/api/sms

Autoryzacja: Bearer token
Oczekiwany typ zawartości: application/json

Pola ciała żądania:

Pole	Typ danych	Opis
`from`	Numeryczny łańcuch znaków, minimum 9 znaków, maksimum 11 znaków (pole opcjonalne)	Numer wirtualnego numeru komórkowego w SENDLY
`to`	Numeryczny łańcuch znaków, minimum 9 znaków, maksimum 11 znaków	Docelowy numer komórkowy
`body`	Łańcuch znaków, minimum 1 znak	Treść wiadomości

Przykładowe żądanie:

curl -X POST https://api.sendly.link/api/sms \
     -H "Authorization: Bearer TWOJ_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "from": "48732129000",
           "to": "48732129001",
           "body": "Test SENDLY"
         }'

Token możliwy jest do wygenerowania i pobrania z panelu klienta. Alternatywnie istnieje możliwość pozyskania tokena przez biuro obsługi klienta.

Możliwe odpowiedzi:

200 – wiadomość została przyjęta do wysyłki

Ciało odpowiedzi:

Pole	Typ danych	Opis
`message_id`	Łańcuch znaków	Unikalny identyfikator wiadomości (16 znaków hex)

Przykładowa odpowiedź:

{"message_id":"a906cff7719bd889"}

Możliwe odpowiedzi błędu:

403 – problem z autoryzacją
422 – problem z walidacją danych
429 – Przekroczono limit żądań

W przypadku błędów ciało odpowiedzi może zawierać jedno lub więcej pól opisanych w tabeli poniżej:

Pole	Typ danych	Opis
`errors.token`	Tablica łańcuchów znaków	Opis błędu związanego z przekazanym tokenem dostępowym
`errors.from`	Tablica łańcuchów znaków	Opis błędu związanego z numerem źródłowym
`errors.to`	Tablica łańcuchów znaków	Opis błędu związanego z numerem docelowym
`errors.body`	Tablica łańcuchów znaków	Opis błędu związanego z ciałem wiadomości

Przykładowa odpowiedź:

{"errors":{"token":["Invalid token"]}}

Wiadomości wychodzące kodowane są w UCS-2 i dzielone co 60 znaków. Opcjonalnie istnieje możliwość wysyłania SMS w kodowaniu GSM7 z ograniczeniem do pojedynczej wiadomości o maksymalnej długości 160 znaków. Opcję tę można włączyć w panelu klienta lub po złożeniu dyspozycji przez biuro obsługi klienta.

1.2 Wysyłka wiadomości na wiele numerów

Jest to metoda API pozwalająca na wysyłkę tej samej wiadomości na wiele numerów. Aktywacja tej funkcji dla tokena dostępowego następuje wyłącznie poprzez kontakt z biurem obsługi klienta. Udostępniany jest następujący endpoint:

POST https://api.sendly.link/api/sms-multi

Autoryzacja: Bearer token
Oczekiwany typ zawartości: application/json

Pola ciała żądania:

Pole	Typ danych	Opis
`from`	Numeryczny łańcuch znaków, minimum 9 znaków, maksimum 11 znaków (pole opcjonalne)	Numer wirtualnego numeru komórkowego w SENDLY
`to`	Tablica numeryczny łańcuchów znaków, minimum 9 znaków, maksimum 11 znaków, minimum 1 element, maksimum 100 elementów	Docelowe numery komórkowe
`body`	Łańcuch znaków, minimum 1 znak	Treść wiadomości

Przykładowe żądanie:

curl -X POST https://api.sendly.link/api/sms-multi \
     -H "Authorization: Bearer TWOJ_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "from": "48732129000",
           "to": ["48732129001", "48732129002"],
           "body": "Test SENDLY"
         }'

Walidacja przesłanych numerów telefonów następuje na zasadzie „wszystko albo nic” – każdy z przesłanych numerów musi być poprawnym polskim numerem komórkowym lub żądanie zostanie odrzucone w całości. Przesłane numery muszą być unikalne, przesłanie zduplikowanych numerów spowoduje odrzucenie żądania w całości.

Możliwe odpowiedzi:

200 – wiadomość została przyjęta do wysyłki

Ciało odpowiedzi:

Pole	Typ danych	Opis
`message_ids`	Tablica obiektów	Każdy ze zwróconych obiektów zawiera pola „number” wskazujący na jeden z podanych numerów docelowych oraz „message_id”, które jest identyfikatorem wiadomości przyjętej do wysyłki

Przykładowa odpowiedź:

{"message_ids":[{"number":"48732129001","message_id":"a906cff7719bd889"}]}

Możliwe odpowiedzi błędu:

403 – problem z autoryzacją
422 – problem z walidacją danych
429 – Przekroczono limit żądań

W przypadku błędów ciało odpowiedzi może zawierać jedno lub więcej pól opisanych w tabeli poniżej:

Pole	Typ danych	Opis
`errors.token`	Tablica łańcuchów znaków	Opis błędu związanego z przekazanym tokenem dostępowym
`errors.from`	Tablica łańcuchów znaków	Opis błędu związanego z numerem źródłowym
`errors.to`	Tablica łańcuchów znaków	Opis błędu związanego z numerem docelowym
`errors.body`	Tablica łańcuchów znaków	Opis błędu związanego z ciałem wiadomości

Przykładowa odpowiedź:

{"errors":{"token":["Invalid token"]}}

1.3 Odbiór wiadomości

Wiadomości przychodzące wysyłane są na podany w panelu klienta webhook. Webhook można także podać w dyspozycji do biura obsługi klienta. Podjęta zostanie jedna próba dostarczenia wiadomości. Żądanie API nie śledzi przekierowań, nie autoryzuje się także do webhooka. Żądanie pochodzić będzie z aktualnego adresu IP domeny api.sendly.link.

Metoda: POST
Typ zawartości: application/json

Pola ciała żądania:

Pole	Typ danych	Opis
`type`	Łańcuch znaków	Typ wiadomości. Dla wiadomości przychodzącej przyjmuje wartość „MESSAGE”
`from`	Łańcuch znaków	Prezentacja numeru źródłowego. W przypadku wiadomości z nadpisanym numerem w tym polu znajduje się nadpis.
`to`	Numeryczny łańcuch znaków	Docelowy numer telefonu
`body`	Łańcuch znaków	Treść wiadomości

Przykładowe ciało żądania:

{"type":"MESSAGE","from":"48732129000","to":"48732129001","body":"Test sms"}

1.4 Potwierdzenie dostarczenia wiadomości

W przypadku chęci otrzymywania powiadomień o dostarczeniu wiadomości należy aktywować tę opcję w panelu klienta lub przez dyspozycję dla biura obsługi klienta. Aktywacja tej opcji spowoduje przesyłanie żądania na podany adres webhooka. Podjęta zostanie jedna próba dostarczenia powiadomienia. Żądanie API nie śledzi przekierowań, nie autoryzuje się także do webhooka. Żądanie pochodzić będzie z aktualnego adresu IP domeny api.sendly.link.

Metoda: POST
Typ zawartości: application/json

Pola ciała żądania:

Pole	Typ danych	Opis
`type`	Łańcuch znaków	Typ wiadomości. Dla wiadomości o statusie przyjmuje wartość „NOTIFICATION”
`message_id`	Łańcuch znaków	Identyfikator wiadomości zwrócony po przyjęciu do wysyłki
`status`	Łańcuch znaków	DELIVERED dla powiadomienia o dostarczeniu. ERROR dla powiadomienia o błędzie.

Przykładowe ciało żądania:

{"type":"NOTIFICATION","message_id":"a906cff7719bd889","status":"DELIVERED"}

2. 3CX SMS API

Ta wersja API obsługuje wysyłkę oraz odbiór wiadomości na podstawie aktualnej specyfikacji centrali 3CX Phone System. Aby aktywować to api, należy w panelu klienta wybrać obie opcje SMS API oraz 3CX SMS API.

Do obsługi połączeń wychodzących konieczne jest podanie w sekcji SMS w 3CX tokenu który można wygenerować w panelu klienta, oraz adresu url:

https://api.sendly.link/api/tcx

Aby obsługiwać wiadomości przychodzące, należy w panelu klienta podać webhook dostępny w centrali 3CX.

Aktywacji może dokonać także biuro obsługi klienta, należy wtedy podać webhook, w odpowiedzi przesłany zostanie token.