Help Center SMSBAT RESTful API vodič

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

Search Results