Přeskočit obsah

SMSBAT RESTful API Guide

Kompletní průvodce SMSBAT RESTful API – vše, co potřebujete vědět.

Poslední aktualizace: 29. srpna 2025

SMSBAT RESTful API umožňuje odesílat různé typy zpráv: Viber-carousel, Viber-survey, Viber-promo (obrázky, video), Viber business chaty, OTP zprávy (Viber OTP, Flash Call) a jejich záložní varianty.

Poznámka: Toto je jednotné HTTP API pro odchozí zprávy. Pokud potřebujete integraci s příchozími roboty (Viber Bot / Telegram Bot), podívejte se na Cascade API.

1. Protokol

  • Protokol: HTTPS
  • Tělo požadavku: Objekt JSON obsahující pole „zpráv“. -Metody:
  • GET pro načtení dat (stav zprávy, zůstatek atd.)
  • POST pro vytvoření objektů (např. zahájení vysílání/odeslání)
  • PATCH pro úpravu objektů

2. Autorizace

Pro vaše pohodlí nabízíme několik způsobů autorizace: - Základní ověřování HTTP (přihlášení a heslo z řídicího panelu). - Vlastní HTTP hlavička X-Authorization-Key obsahující token API. - Pole hesla základní autentizace HTTP obsahující token API (předejte @ jako přihlašovací jméno).

Token API lze vygenerovat na hlavním panelu v části Profil uživatele.

Příklady žádostí

Se základním ověřením: 

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

S 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. Odesílání zpráv

Na platformě SMSBAT je jakékoli odeslání zprávy (dokonce i jedna zpráva) považováno za "Broadcast" (seznam zpráv).

Koncový bod - Metoda: POST - URL: https://api.smsbat.com/bat/messagelist - Headers: Content-Type: application/json

Základní struktura užitečného zatížení: 

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

Povinná pole pro každý objekt zprávy:

  • from: Alfa-název ověřeného odesílatele.
  • to: Telefonní číslo příjemce (formát E.164).
  • type: Výčet typu zprávy.
  • text: Hlavní text zprávy (volitelné, pokud typ nevyžaduje text).

Podporované hodnoty type: - "sms". - viber_service (nebo viber_trans) - viber_promo - viber_carousel - viber_survey - viber_otp - viber_session - flashcall_callback - "flashcall".

Volitelná společná pole:

  • customerMessageId: ID řetězce ve vašem vlastním systému (používá se pro sledování zpětných volání). Musí být jedinečné pro každou zprávu.
  • dtSend: ISO8601 Datum/čas plánovaného budoucího odeslání.
  • dtExpire: ISO8601 Datum/čas termínu dodání.
  • ttl: Time-To-Live v sekundách. (Pokud není zadáno dtExpire, API vypočítá výchozí mapování z type).

Výchozí TTL (sekundy):

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

4. Záložní směrování (kaskádové)

Můžete zadat záložní frontu, která zajistí doručení zprávy, pokud primární kanál selže nebo vyprší.

{
  "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"
        }
      ]
    }
  ]
}
Fallbacks se spouští, když poskytovatel odmítne hlavní zprávu nebo když vyprší TTL.

5. Přehled typů zpráv a data zpráv

Složité typy zpráv vyžadují další konfigurace vložené do vlastnosti messageData.

5.1 Viber Promo (viber_promo)

Pouze obrázek 

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

Text + tlačítko 

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

Obrázek + text + tlačítko Kombinuje img, buttonText a buttonAction.

Úžitkové zatížení videa: 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(Vlastnosti videa můžete také kombinovat s buttonText a buttonAction).

5.2 Viber Transakční / Služba (viber_trans, viber_service)

Pokud máte schválenou šablonu obsahující přiložený soubor: 

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

Vyžaduje pole carousel.items uvnitř messageData.

Omezení: - Délka položek: 2 až 5 položek - Název: 2 až 38 znaků - imageUrl: Doporučená velikost JPEG/PNG 215x185

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

5.4 Průzkum / seznam Viber (viber_survey)

Vytvoří interaktivní hlasování v zobrazení chatu. 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
Vlastnost text zprávy funguje jako název průzkumu (max. 85 znaků). Můžete předat 2 až 5 možností, každá maximálně 50 znaků.

5.5 Viber OTP (viber_otp)

Globálně používá předem registrované lokalizované šablony Viber. 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
Parametry šablony (pin, business_platform_name) přísně rozlišují velká a malá písmena. API podporuje různé jazykové varianty kódu ISO (EN, ES, RU, TR, UK atd.).

5.6 Flash Call (flashcall)

Poslední číslice vytáčecího čísla (vygenerovaný kód) musí být předány přes parametr text. Pokud je vynechán text, kód je náhodný a musíte jej extrahovat z těla synchronní odpovědi 200 OK (zprávy/text) API.

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