Help Center SMSBAT RESTful API Guide

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ť.

{
  "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"
        }
      ]
    }
  ]
}

Záložné reklamy sa spúšťajú, keď poskytovateľ odmietne hlavnú správu alebo keď uplynie platnosť TTL.

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"
}

Search Results