Przejdź do treści

Przewodnik po API RESTful SMSBAT

Kompletny przewodnik po SMSBAT RESTful API – wszystko, co musisz wiedzieć.

Ostatnia aktualizacja: 29 sierpnia 2025

SMSBAT RESTful API umożliwia wysyłanie różnych typów wiadomości: Viber-karuzela, Viber-ankieta, Viber-promo (zdjęcia, wideo), czaty biznesowe Viber, wiadomości OTP (Viber OTP, Flash Call) i ich warianty awaryjne.

Uwaga: Jest to ujednolicony interfejs API HTTP do obsługi wiadomości wychodzących. Jeśli potrzebujesz integracji z botami przychodzącymi (Viber Bot / Telegram Bot), zapoznaj się z Cascade API.

1. Protokół

  • Protokół: HTTPS
  • Treść żądania: Obiekt JSON zawierający tablicę „wiadomości”.
  • Metody:
  • GET, aby pobrać dane (status wiadomości, saldo itp.)
  • POST do tworzenia obiektów (np. inicjowanie transmisji/wysyłania)
  • PATCH do modyfikowania obiektów

2. Autoryzacja

Dla Twojej wygody udostępniamy kilka metod autoryzacji: - Podstawowe uwierzytelnianie HTTP (login i hasło z panelu). - Niestandardowy nagłówek HTTP X-Authorization-Key zawierający token API. - Pole hasła HTTP Basic Authentication zawierające token API (wpisz @ jako login).

Token API można wygenerować w panelu kontrolnym w obszarze Profil użytkownika.

Poproś o przykłady

Z podstawowym uwierzytelnianiem: KOD_BLOKU_0

Z Kluczem autoryzacyjnym X: KOD_BLOKU_1

3. Wysyłanie wiadomości

Na platformie SMSBAT każda wysyłka wiadomości (nawet pojedyncza) traktowana jest jako „Rozgłoszenie” (lista wiadomości).

Punkt końcowy - Metoda: POST - URL: https://api.smsbat.com/bat/messagelist - Nagłówki: Typ zawartości: aplikacja/json

Podstawowa struktura ładunku: KOD_BLOKU_2

Wymagane pola dla każdego obiektu wiadomości:

  • from: Alfa-nazwa zweryfikowanego nadawcy.
  • do: Numer telefonu odbiorcy (format E.164).
  • type: Wyliczenie typu wiadomości.
  • text: Główny tekst wiadomości (opcjonalnie, jeśli typ nie wymaga tekstu).

Obsługiwane wartości typu: - ,,sms'' - viber_service (lub viber_trans) - viber_promo - viber_karuzela - viber_ankieta - viber_otp - viber_sesja - flashcall_callback - „rozmowa błyskawiczna”.

Opcjonalne wspólne pola:

  • customerMessageId: Identyfikator ciągu znaków w Twoim własnym systemie (używany do śledzenia wywołań zwrotnych). Musi być unikalny dla każdej wiadomości.
  • dtSend: ISO8601 Data/godzina zaplanowanej przyszłej wysyłki.
  • dtExpire: ISO8601 Data/godzina terminu dostawy.
  • ttl: Czas życia w sekundach. (Jeśli nie podano dtExpire, API oblicza domyślne mapowanie na podstawie type.

Domyślne TTL (sekundy):

  • sms - 86400 (24h)
  • viber_trans / viber_service - 345600
  • viber_promo - 604800
  • viber_session - 604800

4. Routing awaryjny (kaskadowy)

Można określić kolejkę rezerwową, aby zapewnić dostarczenie wiadomości w przypadku awarii lub wygaśnięcia kanału głównego.

KOD_BLOKU_3 Rezerwy awaryjne są uruchamiane, gdy dostawca odrzuci główny komunikat lub gdy wygaśnie TTL.

5. Przegląd typów wiadomości i danych wiadomości

Złożone typy wiadomości wymagają dodatkowej konfiguracji wprowadzonej do właściwości „messageData”.

Promocja Vibera 5.1 („promocja_vibera”)

Tylko obraz KOD_BLOKU_4

Tekst + Przycisk KOD_BLOKU_5

Obraz + Tekst + Przycisk Łączy img, buttonText i buttonAction.

Ładunek wideo: KOD_BLOKU_6 (Możesz także łączyć właściwości wideo z „buttonText” i „buttonAction”).

5.2 Transakcyjna/usługa Viber (viber_trans, viber_service)

Jeżeli posiadasz zatwierdzony szablon zawierający załączony plik: KOD_BLOKU_7

5.3 Karuzela Vibera („viber_karuzela”)

Wymaga tablicy carousel.items wewnątrz messageData.

Ograniczenia: - Długość elementów: od 2 do 5 elementów - Tytuł: od 2 do 38 znaków - imageUrl: zalecany rozmiar JPEG/PNG 215x185

KOD_BLOKU_8

5.4 Ankieta/Lista Vibera (viber_survey)

Tworzy interaktywną ankietę w widoku czatu. KOD_BLOKU_9 Właściwość text wiadomości pełni rolę tytułu ankiety (maks. 85 znaków). Możesz przekazać od 2 do 5 opcji, każda zawierająca maksymalnie 50 znaków.

5.5 Viber OTP (viber_otp)

Korzysta z zarejestrowanych wcześniej zlokalizowanych szablonów Viber na całym świecie. KOD_BLOKU_10 W parametrach szablonu („pin”, „nazwa_platformy_biznesowej”) uwzględniana jest wielkość liter. API obsługuje różne warianty języka kodu ISO (EN, ES, RU, TR, UK itp.).

5.6 Połączenie błyskawiczne („rozmowa błyskawiczna”)

Ostatnie cyfry wybieranego numeru (wygenerowany kod) należy przekazać poprzez parametr text. Jeśli pominięto „tekst”, kod jest losowy i należy go wyodrębnić z synchronicznej treści odpowiedzi API 200 OK („wiadomości/tekst”).

KOD_BLOKU_11