SMSBAT RESTful API vodič

Kompletan vodič za SMSBAT RESTful API – sve što trebate znati.

_Posljednje ažuriranje: 29. avgusta 2025.

SMSBAT RESTful API vam omogućava slanje različitih tipova poruka: Viber-vrtuljak, Viber-anketa, Viber-promo (slike, video), Viber poslovni razgovori, OTP poruke (Viber OTP, Flash Call) i njihove rezervne varijante.

Napomena: Ovo je objedinjeni HTTP API za odlazne poruke. Ako su vam potrebne integracije sa ulaznim botovima (Viber Bot / Telegram Bot), pogledajte Cascade API.

---

1. Protokol

• Protokol: HTTPS
• Tijelo zahtjeva: JSON objekat koji sadrži niz poruka.
• Metode:
• GET za preuzimanje podataka (status poruke, stanje, itd.)
• POST za kreiranje objekata (npr. pokretanje emitiranja/otpremanja)
• PATCH za izmjenu objekata

2. Autorizacija

Nudimo nekoliko metoda autorizacije za vašu udobnost: - HTTP Basic Authentication (prijava i lozinka sa vaše kontrolne table). - Prilagođeno HTTP zaglavlje X-Authorization-Key koje sadrži API token. - Polje lozinke HTTP Basic Authentication sadrži API token (pronesite @ kao prijavu).

API token može se generirati na kontrolnoj tabli pod Korisnički profil.

Primjeri zahtjeva

Sa osnovnim autentifikacijom:

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

Sa 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. Slanje poruka

U SMSBAT platformi, svako slanje poruke (čak i pojedinačna poruka) smatra se "Emitovanjem" (listom poruka).

Krajnja tačka - Metoda: POST - URL: https://api.smsbat.com/bat/messagelist - Zaglavlja: Content-Type: application/json

Osnovna struktura nosivosti:

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

Obavezna polja za svaki objekt poruke:

• od: Alfa-ime verifikovanog pošiljaoca.
• za: Broj telefona primaoca (format E.164).
• type: enum tipa poruke.
• tekst: Glavni tekst poruke (opcionalno ako tip ne zahtijeva tekst).

Podržane vrijednosti type: - sms - viber_service (ili viber_trans) - viber_promo - viber_carousel - viber_survey - viber_otp - viber_session - flashcall_callback - flashcall

Opciona zajednička polja:

• customerMessageId: ID niza unutar vašeg vlastitog sistema (koristi se za praćenje povratnih poziva). Mora biti jedinstven po poruci.
• dtSend: ISO8601 Datum/Vrijeme planiranog budućeg slanja.
• dtExpire: ISO8601 Datum/Vrijeme roka isporuke.
• ttl: Vrijeme za život u sekundama. (Ako dtExpire nije naveden, API izračunava mapiranje zadanih vrijednosti iz type).

Zadani TTL (sekunde):

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

---

4. Rezervno usmjeravanje (kaskadno)

Možete odrediti rezervni red kako biste osigurali isporuku poruke ako primarni kanal ne uspije ili istekne.

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

Povratne informacije se aktiviraju kada dobavljač odbije glavnu poruku ili kada TTL istekne.

---

5. Pregled vrsta poruka i podataka o porukama

Složeni tipovi poruka zahtijevaju dodatne konfiguracije koje se ubacuju u svojstvo messageData.

5.1 Viber Promo (viber_promo)

Samo slika

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

Tekst + Dugme

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

Slika + Tekst + Dugme Kombinira img, buttonText i buttonAction.

Pojašnjenje videa:

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

(Možete i kombinovati svojstva videa sa buttonText i buttonAction).

---

5.2 Viber transakcija / usluga (viber_trans, viber_service)

Ako imate odobreni predložak koji sadrži priloženi fajl:

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

---

5.3 Viber vrtuljak (viber_carousel)

Zahtijeva niz carousel.items unutar messageData.

Ograničenja: - Dužina predmeta: između 2 i 5 stavki - Naslov: 2 do 38 znakova - imageUrl: JPEG/PNG preporučena veličina 215x185

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

---

5.4 Viber anketa / lista (viber_survey)

Kreira interaktivnu anketu unutar prikaza chata.

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

Svojstvo text poruke djeluje kao naslov ankete (maksimalno 85 znakova). Možete proslijediti između 2 i 5 opcija, svaka od maksimalno 50 znakova.

---

5.5 Viber OTP (viber_otp)

Koristi unaprijed registrirane lokalizirane Viber šablone globalno.

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

Parametri predloška (pin, business_platform_name) strogo su osjetljivi na velika i mala slova. API podržava različite varijante jezika ISO koda (EN, ES, RU, TR, UK, itd.).

---

5.6 Flash poziv (flashcall)

Posljednje cifre broja za biranje (generirani kod) moraju biti proslijeđene preko parametra text. Ako je tekst izostavljen, kod je nasumičan i morate ga izdvojiti iz API-jevog sinhronog tijela odgovora 200 OK (messages/text).

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