Zgodność API Messages

SMSBAT obsługuje warstwę zgodności z Messagio API. Umożliwia to migrację istniejących integracji Vibera zaprojektowanych dla Messagio bezpośrednio do SMSBAT bez konieczności przepisywania struktury ładunku lub zmiany logiki integracji.

Ustawienia połączenia

Aby kierować żądania przez SMSBAT, zaktualizuj podstawowy adres URL i dane uwierzytelniające w swojej integracji:

Podstawowy adres URL: https://restapi.smsbat.com
Punkt końcowy: POST /api/SendMessage
Format żądania: application/x-www-form-urlencoded (dane formularza)

Uwierzytelnianie i dane uwierzytelniające

Żądania są uwierzytelniane przy użyciu parametrów wysyłanych bezpośrednio w danych formularza treści żądania:

Parametr	Wpisz	Wymagane	Opis
`użytkownik`	ciąg	Tak	Twój login do konta SMSBAT lub identyfikator użytkownika.
`znak`	ciąg	Tak	Sekret API lub podpis zarejestrowany dla nazwy nadawcy.
`od`	ciąg	Tak	Zarejestrowana nazwa alfa nadawcy.
`metoda_wysyłania`	ciąg	Tak	Typ kanału. Użyj `viber` w przypadku zwykłych wiadomości Viber Business lub `viber_otp` w przypadku szablonów Viber OTP.
`telefon`	ciąg	Tak	Numer telefonu odbiorcy w formacie międzynarodowym (np. „380501234567”).

Typy wiadomości Viber

Wybierz kartę poniżej, aby wyświetlić określone parametry i zażądać ładunków dla różnych struktur wiadomości Viber:

=== „Wiadomość tekstowa”

Wysyła prostą wiadomość tekstową.

**Dodatkowe parametry:**

| Parametr | Wpisz | Wymagane | Opis |
| :--- | :--- | :--- | :--- |
| `txt` | ciąg | **Tak** | Tekst wiadomości. |

**Poproś o przykład ładunku:**
__KOD_BLOKU_0__

=== „Tekst + przycisk”

Wysyła wiadomość tekstową z interaktywnym przyciskiem wezwania do działania.

**Dodatkowe parametry:**

| Parametr | Wpisz | Wymagane | Opis |
| :--- | :--- | :--- | :--- |
| `txt` | ciąg | **Tak** | Tekst wiadomości. |
| `tekst_przycisku` | ciąg | **Tak** | Tekst wyświetlany na przycisku. |
| `link_przycisku` | ciąg | **Tak** | Docelowy adres URL po kliknięciu przycisku. |

**Poproś o przykład ładunku:**
__KOD_BLOKU_1__

=== „Wiadomość obrazkowa”

Wysyła publiczny plik obrazu.

**Dodatkowe parametry:**

| Parametr | Wpisz | Wymagane | Opis |
| :--- | :--- | :--- | :--- |
| `link do_obrazu` | ciąg | **Tak** | Publiczny adres URL obrazu HTTPS. |
| `txt` | ciąg | Nie | Opcjonalny tekst podpisu do wyświetlenia pod obrazem. |

**Poproś o przykład ładunku:**
__KOD_BLOKU_2__

=== „Tekst + obraz + przycisk”

Wysyła bogatą kartę zawierającą tekst, obraz i przycisk.

**Dodatkowe parametry:**

| Parametr | Wpisz | Wymagane | Opis |
| :--- | :--- | :--- | :--- |
| `txt` | ciąg | **Tak** | Tekst podpisu. |
| `link do_obrazu` | ciąg | **Tak** | Publiczny adres URL obrazu HTTPS. |
| `tekst_przycisku` | ciąg | **Tak** | Tekst wyświetlany na przycisku. |
| `link_przycisku` | ciąg | **Tak** | Docelowy adres URL po kliknięciu przycisku. |

**Poproś o przykład ładunku:**
__KOD_BLOKU_3__

=== „Wiadomość wideo”

Wysyła plik wideo z opcjonalnym podpisem tekstowym i przyciskami akcji.

**Dodatkowe parametry:**

| Parametr | Wpisz | Wymagane | Opis |
| :--- | :--- | :--- | :--- |
| `wideo.url` | ciąg | **Tak** | Publiczny adres URL HTTPS pliku wideo. |
| `wideo.miniatura` | ciąg | **Tak** | Publiczny adres URL HTTPS obrazu podglądu wideo. |
| `wideo.rozmiar_mb` | liczba całkowita | **Tak** | Przybliżony rozmiar pliku wideo w megabajtach. |
| `wideo.czas trwania_sek` | liczba całkowita | **Tak** | Czas trwania filmu w sekundach. |
| `txt` | ciąg | Nie | Opcjonalny tekst opisu. |
| `tekst_przycisku` | ciąg | Nie | Opcjonalny tekst przycisku (może pełnić funkcję podpisu lub łącza). |
| `link_przycisku` | ciąg | Nie | Opcjonalny adres URL łącza przycisku. |

**Poproś o przykład ładunku:**
__KOD_BLOKU_4__

=== „Szablon OTP”

Wysyła hasła jednorazowe Viber (OTP) przy użyciu wstępnie zatwierdzonego szablonu.

!!! uwaga
    Wysyłając wiadomości OTP, musisz ustawić `sending_method` na `viber_otp`.

Dodatkowe parametry:

| Parametr | Wpisz | Wymagane | Opis |
| :--- | :--- | :--- | :--- |
| `template.id` | ciąg | **Tak** | Wstępnie zatwierdzony identyfikator szablonu Viber OTP. |
| `szablon.lang` | ciąg | **Tak** | Kod języka szablonu (np. „en”, „uk”). |
| `szablon.params.pin` | ciąg | **Tak** | Wartość PIN OTP do wstrzyknięcia do szablonu. |
| `template.params.business_platform_name` | ciąg | **Tak** | Symbol zastępczy nazwy firmy w szablonie. |
| `template.params.code_validity_time` | ciąg | **Tak** | Okres ważności PIN-u w minutach. |

**Poproś o przykład ładunku:**
__KOD_BLOKU_5__

=== „Wiadomość karuzeli”

Wysyła interaktywną kartę wiadomości zawierającą wiele slajdów (kart), po których użytkownik może przesuwać palcem.

**Dodatkowe parametry:**

| Parametr | Wpisz | Wymagane | Opis |
| :--- | :--- | :--- | :--- |
| `txt` | ciąg | **Tak** | Tekst tytułu karuzeli. |
| `karuzela[N].tytuł` | ciąg | **Tak** | Tytuł karty „N” (zaczynając od 0). |
| `karuzela[N].image_url` | ciąg | **Tak** | Adres URL publicznego obrazu HTTPS karty „N”. |
| `karuzela[N].podstawowa_etykieta` | ciąg | **Tak** | Napis na głównym przycisku karty „N”. |
| `karuzela[N].podstawowy_url` | ciąg | **Tak** | Adres URL łącza głównego przycisku karty „N”. |
| `karuzela[N].etykieta_wtórna` | ciąg | Nie | Podpis przycisku dodatkowego karty „N”. |
| `karuzela[N].wtórny_url` | ciąg | Nie | Adres URL łącza dodatkowego przycisku karty „N”. |

**Poproś o przykład ładunku:**
__KOD_BLOKU_6__

=== „Wiadomość ankietowa”

Wysyła wiadomość zawierającą interaktywną ankietę lub pytanie z ankiety.

**Dodatkowe parametry:**

| Parametr | Wpisz | Wymagane | Opis |
| :--- | :--- | :--- | :--- |
| `txt` | ciąg | **Tak** | Tekst pytania ankiety. |
| `opcje_ankiety[N]` | ciąg | **Tak** | Tekst opcji ankiety dla pozycji „N” (indeks zaczynający się od 0). Wymagane są co najmniej 2 opcje. |
| `typ_opcji` | liczba całkowita | **Tak** | Typ selektora: `1` (RadioButtons) lub `2` (zwykłe przyciski). |

**Poproś o przykład ładunku:**
__KOD_BLOKU_7__

Format odpowiedzi

Punkt końcowy zgodności API Messagio zwraca odpowiedzi w formacie XML z kodem stanu „HTTP 200 OK”.

Odpowiedź zaakceptowana (powodzenie).

KOD_BLOKU_8

Odpowiedzi na błędy

Jeśli weryfikacja parametrów żądania nie powiedzie się lub uwierzytelnienie nie powiedzie się, odpowiedź zwróci kod niezerowy.

=== „Brakujący podpis” KOD_BLOKU_9

=== „Nieautoryzowane” KOD_BLOKU_10

Oddzwonienia

Adresy URL wywołania zwrotnego muszą być zaimplementowane i hostowane na Twojej platformie. SMSBAT wysyła wywołania zwrotne HTTP w celu aktualizacji systemu w zakresie zdarzeń dostawy, odpowiedzi na ankiety i odpowiedzi użytkowników.

1. Oddzwonienie dotyczące statusu dostawy

Wysyłane w przypadku zmiany statusu wiadomości (dostarczona, przeczytana, nieudana).

Typ zawartości: application/x-www-form-urlencoded
Metoda: POST

Poproś o formaty ładunku:

Dostarczono: KOD_BLOKU_11
Widział/Przeczytał: KOD_BLOKU_12
Niedostarczone / Nieudane: KOD_BLOKU_13

Opis pól:

msg_id: unikalny identyfikator wiadomości SMSBAT (GUID) zwrócony w odpowiedzi SendMessage.
status: Wynik dostawy („dostarczona”, „niedostarczona” lub „status nieznany”).
type: Ustaw na widziany, gdy wiadomość została wyświetlona przez odbiorcę.
status_extended: Określona przyczyna techniczna niedostarczenia statusu (np. VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE.

2. Oddzwonienie z odpowiedzią na ankietę

Wywoływane, gdy użytkownik wybierze opcję odpowiedzi w wiadomości z ankiety Viber.

Typ zawartości: application/x-www-form-urlencoded
Metoda: POST

Poproś o format ładunku: KOD_BLOKU_14

3. Przychodzące wywołanie zwrotne w postaci wiadomości użytkownika

Wywoływane, gdy użytkownik wyśle wiadomość SMS lub wiadomość multimedialną z powrotem do Twojej usługi Viber Business.

Typ zawartości: aplikacja/json
Metoda: POST

Poproś o format ładunku: KOD_BLOKU_15

Opis pól:

msg_id: Unikalny identyfikator wiadomości wygenerowany dla odpowiedzi przychodzącej.
text: Treść tekstowa wysłana przez użytkownika (może mieć wartość null, jeśli wysłał tylko multimedia).
media: Bezpośredni adres URL umożliwiający pobranie wszelkich załączników multimedialnych przesłanych przez użytkownika (może mieć wartość null, jeśli jest to tylko tekst).
telefon: numer telefonu nadawcy w formacie międzynarodowym.
sender_bm_id: Identyfikator nadawcy Viber Business.