HTTPS API v2 / Wysyłanie wiadomości RCS
Wywołanie adresu
Aby przy pomocy Zdalnej obsługi wysłać wiadomość RCS należy przesłać określone zgłoszenie protokołem HTTP lub HTTPS metodą POST.
messages/send_rcs
Dostępne parametry
| Parametr | Typ | Przykładowa wartość lub format | Opis |
|---|---|---|---|
| username | String | login | Login użytkownika API. |
| password | String | haslo | Hasło użytkownika API. |
| rcs_id | String | Identyfikator RCS np. 54c53be2-cbb8-11ec-9d64-0242ac120002 | Identyfikator dostepny jest w naszym panelu, przypisany dla każdej stworzonej konfiguracji agenta RCS. |
| phone | String|Array | +48500600700 | Numer lub tablica numerów telefonów. |
| message | Array | [] | Struktura wiadomości RCS w postaci Array. |
| details | Boolean | true, false lub brak | Parametr wyświetlający w odpowiedzi zwrotnej szczegóły wysłanych wiadomości. |
| date | DateTime | ISO np. „2015-02-22 12:25:55” |
Parametr opcjonalny, pozwalający na określenie terminu wysyłki wiadomości. |
| unique_id | String|Array | np. 6asTD3fif98gj | Parametr opcjonalny, pozwalający na zdefiniowanie własnego identyfikatora wysyłanej wiadomości. Identyfikator może mieć minimalnie 3 znaki i maksymalnie 50 znaków alfanumerycznych (a-z, A-Z, 0-9). Dla grupowych wysyłek, kolejne unique_id muszą być unikalne oraz ilość unique_id musi być zgodna z ilością numerów. |
| group_id | String|Array | np. 123456789 |
Identyfikator lub identyfikatory grup w Panelu Klienta. Identyfikatory te można pobrać korzystając z akcji groups/index lub kopiując je z poziomu edycji grupy w Panelu Klienta. |
Parametry oznaczone pogrubieniem są obowiązkowe. Pozostałe są opcjonalne.
Dostępne struktury wiadomości
1. Wiadomość tekstowa
{
"text":"Przyklad wiadomości",
"suggestions":[]
}
2. Wiadomość file/video
{
"file":{
"name":"Nazwa pliku",
"url":"https://sciezka_do_plik_video",
"type":"video/mp4",
"size":1489039
},
"suggestions":[]
}
3. Wiadomość karta informacyjna (pojedyncza)
{
"richcard":[{
"title":"RCS",
"description":"Opis wiadomosci",
"media": {
"url":"https://sciezka_do_pliku",
"size":26802,
"type":"image/png",
"thumbnail":"https://sciezka_do_mini_obrazka",
"thumbnailSize":2802,
"thumbnailType":"image/jpeg",
},
"suggestions":[],
"layout": {
"imageAlignment":"LEFT|RIGHT",
"cardOrientation":"VERTICAL|HORIZONTAL",
}
}],
"suggestions":[]
}
4. Wiadomość karta informacyjna (karuzela)
{
"richcard":[{
"title":"RCS",
"description":"Opis pierwszej wiadomosci",
"media": {
"url":"https://sciezka_do_pliku",
"size":26802,
"type":"image/png",
"thumbnail":"https://sciezka_do_mini_obrazka",
"thumbnailSize":2802,
"thumbnailType":"image/jpeg",
"height":"SHORT|MEDIUM|TALL"
},
"suggestions":[]
},
{
"title":"RCS",
"description":"Opis drugiej wiadomosci",
"media": {
"url":"https://sciezka_do_pliku",
"size":26802,
"type":"image/png",
"thumbnail":"https://sciezka_do_mini_obrazka",
"thumbnailSize":2802,
"thumbnailType":"image/jpeg",
"height":"SHORT|MEDIUM|TALL"
},
"suggestions":[]
}],
"cardWidth":"SMALL|MEDIUM",
"suggestions":[]
}
Wiadomość typu 'kazruzela' może zawierać maksymalnie 4 elementy. W przypadku użycia struktury 'media' wymagane jest podanie elementów 'url', 'size' oraz 'type'. Poniżej lista obsługiwanych typów multimediów:
| Typ nośnika | Typ dokumentu | Rozszerzenie | Działa z kartami informacyjnymi |
|---|---|---|---|
| application/ogg | Dźwięk OGG | .ogx | Nie |
| application/pdf | Nie | ||
| audio/aac | Dźwięk AAC | .aac | Nie |
| audio/mp3 | format dźwięku MP3 | .mp3 | Nie |
| audio/mpeg | Dźwięk MPEG | .mpeg | Nie |
| audio/mpg | Dźwięk MPG | .mp3 | Nie |
| audio/mp4 | Dźwięk MP4 | .mp4 | Nie |
| audio/mp4-latm | Dźwięk MP4-latm | .mp4 | Nie |
| audio/3gpp | Audio 3GPP | .3gp | Nie |
| image/jpeg | JPEG | .jpeg, .jpg | Tak |
| image/gif | GIF | .gif | Tak |
| image/png | PNG | .png | Tak |
| video/h263 | Film H263 | .h263 | Tak |
| video/m4v | Film M4V | .m4v | Tak |
| video/mp4 | Film MP4 | .mp4 | Tak |
| video/mpeg4 | Film w formacie MPEG-4 | .mp4, .m4p | Tak |
| video/mpeg | MPEG-video | .mpeg | Tak |
| video/webm | Film WEBM | .webm | Tak |
Sugestie
Element sugestii nie jest wymagany, jednak pozwala na dodanie dodatkowych buttonów, które umozliwiają miedzy innymi przekierowanie użytkownika do strony www, wykonanie call, skierowanie do poczty lub odesłanie wiadomości zwrotnej. Do dypozycji mamy więc cztery opcje 'url', 'dial', 'map', 'calendar' i odpowiednio parametr 'to' odpowiada wartości, np. dla typu 'url' będzie to adres URL, dla 'dial' numer telefonu, 'map' współrzedne, oraz 'calendar' informację nt. zdarzenia.
Poniżej przedstawione zostały możliwe struktury:
[
{
"reply":{
"text":"Label",
"postback":"uslugi",
}
},
{
"action":{
"text":"Label",
"postback":"my_url",
"action":"url",
"to":"https://adres_url_do_przekierowania",
}
},
{
"action":{
"text":"Label",
"postback":"my_dial",
"action":"dial",
"to":"+48100100100",
}
},
{
"action":{
"text":"Label",
"postback":"my_map",
"action":"map",
"to":"SerwerSMS|50.0904966|18.5803288",
}
},
{
"action":{
"text":"Label",
"postback":"my_calendar",
"action":"calendar",
"to":"2022-04-05 09:00:00|2022-04-05-10:00:00|Wydarzenie",
}
}
]
Ciąg znaków zawarty w tablicy pod kluczem 'postback' identyfikuje zdarzenie, które zostanie nastepnie przekazane w formie PUSH na zdefiniowany adres URL Webhook. W ten sposób można realizować scenariusz automatycznych odpowiedzi, jako reakacja na odpowiednie zachowanie użytkownika. Maksymalna ilość znaków identyfikująca treść buttona (pole 'text') wynosi 25.
Maksymalna ilośc elementów wynosi 11, jednak w przypadku stosowania dodatkowej grafiki lub dłuższego opisu, ilość wyświetlonych elmenetów może byc mniejsza.
W zależności od przesłanych danych SerwerSMS.pl wygeneruje w odpowiedzi dokument w formacie JSON/XML z informacją na temat wykonanych akcji. I tak w przypadku prawidłowego wysłania wiadomości SMS klient otrzyma przykładowo następują informację:
{
"success":true,
"queued":1,
"unsent":0
}
W przypadku podania dodatkowego parametru details=true, odpowiedź zwrotna zostanie uzupełniona o szczegóły wysyłanych wiadomości, które można zapisać w bazie danych po stronie oprogramowania klienta:
{
"success":true,
"queued":1,
"unsent":0,
"items":[{
"id":"1c142d81c7",
"phone":"+48500600700",
"status":"queued",
"queued":"2014-10-16 16:49:05",
"text":"Test SerwerSMS.pl"
}]
}
Parametr "success" zawiera informację o powodzeniu przeprowadzonej operacji. W atrybutach "queued" oraz "unset" znajdują się liczby skolejkowanych oraz niewysłanych wiadomości. Sekcja "items" zawiera numery telefonów i ID wiadomości przekazanych do wysłania (oraz wiadomości, których nie skolejkowano z określonego powodu). Unikalny znacznik wiadomości SMS może być wykorzystany później do sprawdzenia w sposób zdalny stanu wysyłki konkretnej wiadomości SMS. W parametrze "text" widnieje treść wysyłanej wiadomości SMS. Numer telefonu jest automatycznie poprawiany i wyświetlany w pełnym formacie wymaganym przez SerwerSMS.pl czyli z numerem kierunkowym kraju (np. +48) na początku.
Oprócz tego może zostać wygenerowany błąd ogólny gdzie nie ma rozgraniczenia na skolejkowane i błędne. Może to nastąpić np. w sytuacji gdy klient nie zdefiniuje treści wiadomości, nie poda numerów telefonów, jego konto nie jest aktywne lub wystąpił inny problem opisany w komunikatach błędów. W przypadku braku odpowiedniego uprawnienia zostanie wygenerowany następujący komunikat:
{
"error":{
"code":6300,
"type":"RcsError",
"message":"Brak uprawnień do wysyłki wiadomości"
}
}
Komunikaty błędów
| Kod błędu | Opis |
|---|---|
| 6300 | Brak uprawnień do wysyłki wiadomości |
| 6301 | Nieprawidłowa identyfikacja agenta RCS lub konfiguracja jest nieaktywna |
| 6302 | Struktura wiadomości jest nieprawidłowa |
| 6303 | Brak wymaganych parametrów |
| 6304 | Nieprawidłowy adres IP |
| 6306 | Nieprawidłowy numer telefonu |
| 6307 | Pusta struktura wiadomości |
| 6308 | Ustaw wybrany typ wiadomości (text, audio, file, richcard) |
| 6309 | Struktura sugestii jest nieprawidłowa |
| 6310 | Treść wiadomości jest pusta |
| 6311 | Struktura Audio message jest nieprawidłowa lub brak wymaganych parametrów (name, file) |
| 6312 | Struktura File message jest nieprawidłowa lub brak wymaganych parametrów (name, url, mime, size) |
| 6313 | Struktura Richcard message jest nieprawidłowa lub brak wymaganych parametrów (title, description, media) |
| 6314 | Struktura Map message jest nieprawidłowa |
| 6315 | Błąd ogólny |
| 6317 | Sieć nieobsługiwana |
Powiadomienia URL
Na określony w panelu adres Webhook (definiowany podczas konfiguracji agenta RCS) przekazywane jest powiadomienie URL, które definiuje raport, akcje zwrotną użytkownika (np. klikniecie z wybraną sugestię) lub wpisaną odpowiedź zwrotną użytkownika. Wyróżniamy więc trzy podstawowe struktury, rozróżniane polem 'type', są to 'report', 'reply', 'action' oraz 'message'. Dane wysyłane są metodą POST w postaci struktury JSON. Wysyłka powiadomienia realizowana jest z adresu IP 94.152.153.158.
Struktura dla powiadomienia 'report' (stan wysłanej wiadomosci RCS):
[{
"type":"report",
"status":"displayed",
"smsid":"7HydhfmN",
"rcs_id":"c6dyuf34-abYh-oPlo-jusYqPl9IkNs",
"phone":"+48100100100",
"date":"2022-05-04 16:55:45"
}]
Struktura dla powiadomienia 'reply' oraz 'action' (zdarzenie wykonane przez użytkownika):
[{
"type":"reply|action",
"data":"uslugi",
"text":"VXNsdWdp",
"rcs_id":"c6dyuf34-aauh-1dkj-dhfbbtldngh1",
"phone":"+48100100100",
"msgid":"Mx1j==djUhfjHfkghNfhg",
"date":"2022-05-04 16:55:45"
}]
Struktura dla powiadomienia 'message' (wiadomość odesłana przez użytkownika):
[{
"type":"message",
"text":"VHJlc2Mgd2lhZG9tb3NjaQ==",
"rcs_id":"c6dyuf34-aauh-1dkj-dhfbbtldngh1",
"phone":"+48100100100",
"msgid":"AMx1jdjUfhfjHfkghNfhg",
"date":"2022-05-04 16:55:45"
}]
W panelu klienta dla wybranej konfiguracji można określić tag poprawnej odpowiedzi. Jeśli wprowadzono jakiś ciąg znaków mechanizm bedzie oczekiwał zgodnej odpowiedzi, w przeciwnym razie będzie ponawiał request co 30min do osiągnięcia maksymalnie 5 prób.
Informacja zawarta w elemencie 'text' jest zakodowana w formie base64.
Zalecane ustawienia
W przypadku średnich i dużych ilości wysyłanych wiadomości rzędu kilku tysięcy lub więcej, zalecane jest przekazywanie wiadomości w „paczkach” po ok 50 numerów w jednym zapytaniu. Przyspieszy to znacznie proces przekazywania danych do SerwerSMS.pl i zmniejszy ilość koniecznych do wysłania zapytań.