SMSBAT RESTful API Guide

Kompletný sprievodca SMSBAT RESTful API – všetko, čo potrebujete vedieť.

Posledná aktualizácia: 29. augusta 2025

SMSBAT RESTful API vám umožňuje posielať rôzne typy správ: Viber-carousel, Viber-survey, Viber-promo (obrázky, video), Viber business chaty, OTP správy (Viber OTP, Flash Call) a ich záložné varianty.

Poznámka: Toto je jednotné HTTP API pre odchádzajúce správy. Ak potrebujete integráciu s prichádzajúcimi robotmi (Viber Bot / Telegram Bot), pozrite si Cascade API.

1. Protokol

Protokol: HTTPS
Telo požiadavky: Objekt JSON obsahujúci pole „správ“. -Metódy:
„GET“ na načítanie údajov (stav správy, zostatok atď.)
„POST“ na vytvorenie objektov (napr. spustenie vysielania/odoslania)
PATCH na úpravu objektov

2. Autorizácia

Pre vaše pohodlie poskytujeme niekoľko spôsobov autorizácie: - HTTP Basic Authentication (prihlasovacie meno a heslo z vášho dashboardu). - Vlastná hlavička HTTP „X-Authorization-Key“ obsahujúca token rozhrania API. - Pole s heslom základnej autentifikácie HTTP obsahujúce token API (ako prihlasovacie meno zadajte @).

Token API je možné vygenerovať na informačnom paneli v časti Profil používateľa.

Príklady žiadostí

So základnou autorizáciou:

curl -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist \
  --user user:password

S kľúčom X-Authorization-Key:

curl -H "X-Authorization-Key: <token>" \
  -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist

3. Odosielanie správ

V platforme SMSBAT sa každé odoslanie správy (aj jedna správa) považuje za "Broadcast" (zoznam správ).

Koncový bod - Spôsob: POST - URL: https://api.smsbat.com/bat/messagelist - Hlavičky: Typ obsahu: application/json

Základná štruktúra užitočného zaťaženia:

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "text": "Check out our new products!",
      "type": "viber_carousel",
      "ttl": 300,
      "messageData": { ... }
    }
  ]
}

Povinné polia pre každý objekt správy:

from: Alfa-názov overeného odosielateľa.
to: Telefónne číslo príjemcu (formát E.164).
type: Výčet typu správy.
text: Hlavný text správy (voliteľné, ak typ nevyžaduje text).

Podporované hodnoty type: - „sms“. - viber_service (alebo viber_trans) - viber_promo - viber_carousel - "viber_prieskum". - viber_otp - „viber_session“. - flashcall_callback - „flashcall“.

Voliteľné spoločné polia:

customerMessageId: ID reťazca vo vašom vlastnom systéme (používa sa na sledovanie spätných volaní). Musí byť jedinečné pre každú správu.
dtSend: ISO8601 Dátum/čas plánovaného budúceho odoslania.
dtExpire: ISO8601 Dátum/čas termínu dodania.
ttl: Time-To-Live v sekundách. (Ak nie je zadané dtExpire, API vypočíta mapovanie predvolených hodnôt z type).

Predvolené hodnoty TTL (sekundy):

– „sms“ – 86 400 (24 hodín) - viber_trans / viber_service - 345600 - viber_promo - 604800 - "viber_session" - 604800

4. Záložné smerovanie (kaskádové)

Môžete zadať záložný front na zabezpečenie doručenia správ, ak primárny kanál zlyhá alebo vyprší platnosť.

Záložné reklamy sa spúšťajú, keď poskytovateľ odmietne hlavnú správu alebo keď uplynie platnosť TTL. href="#__codelineno-3-1">{ "messages": [ { "from": "ALPHANAME", "to": "380500505051", "text": "test message", "type": "viber_service", "ttl": 60, "fallbacks": [ { "from": "ALPHANAME", "to": "380936670003", "text": "test sms fallback message2", "type": "sms" } ] } ] }

5. Prehľad typov správ a údaje o správach

Komplexné typy správ vyžadujú dodatočné konfigurácie vložené do vlastnosti messageData.

5.1 Viber Promo (`viber_promo`)

Len obrázok

"messageData":{
  "img":"https://domain.com/image.png"
}

Text + tlačidlo

"messageData":{
  "buttonText":"Save Now",
  "buttonAction":"https://help.smsbat.com"
}

Obrázok + text + tlačidlo Kombinuje img, buttonText a buttonAction.

Užitočné zaťaženie videa:

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}

(Vlastnosti videa môžete skombinovať aj s buttonText a buttonAction).

5.2 Viber Transactional / Služba (`viber_trans`, `viber_service`)

Ak máte schválenú šablónu obsahujúcu priložený súbor:

"messageData": {
  "fileUrl": "https://domain.com/receipt.pdf",
  "fileName": "Receipt.pdf",
  "fileType": "pdf"
}

5.3 Viber Carousel (`viber_carousel`)

Vyžaduje pole carousel.items v messageData.

Obmedzenia: - Dĺžka položiek: 2 až 5 položiek - Názov: 2 až 38 znakov - imageUrl: Odporúčaná veľkosť JPEG/PNG 215 x 185

"messageData": {
  "carousel": {
    "items": [
      {
        "title": "50% Off Shoes!",
        "imageUrl": "https://domain.com/image1.png",
        "primaryButton": { "label": "Shop", "actionUrl": "..." },
        "secondaryButton": { "label": "Details", "actionUrl": "..." }
      }
    ]
  }
}

5.4 Prieskum/zoznam Viber (`viber_survey`)

Vytvorí interaktívny prieskum v rámci zobrazenia rozhovoru.

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}

Vlastnosť „text“ správy funguje ako názov prieskumu (max. 85 znakov). Môžete prejsť 2 až 5 možnosťami, každá má maximálne 50 znakov.

5.5 Viber OTP (`viber_otp`)

Globálne používa vopred zaregistrované lokalizované šablóny Viber.

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}

Parametre šablóny (pin, business_platform_name) striktne rozlišujú malé a veľké písmená. Rozhranie API podporuje rôzne jazykové varianty kódu ISO ("EN", "ES", "RU", "TR", "UK" atď.).

5.6 Flash Call (`flashcall`)

Posledné číslice vytáčaného čísla (vygenerovaný kód) musia byť odovzdané cez parameter text. Ak sa vynechá text, kód je randomizovaný a musíte ho extrahovať z tela synchrónnej odpovede 200 OK (správy/text) rozhrania API.

{
  "from": "FLASHCALL",
  "to": "380500000000",
  "type": "flashcall",
  "text": "340"
}