Preskoči na sadržaj

Vodič za SMSBAT RESTful API

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

Zadnje ažuriranje: 29. kolovoza 2025

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

Napomena: Ovo je objedinjeni HTTP API za izlazne poruke. Ako trebate integracije s dolaznim botovima (Viber Bot / Telegram Bot), pogledajte Cascade API.

1. Protokol

  • Protokol: HTTPS
  • Tijelo zahtjeva: JSON objekt koji sadrži niz poruka.
  • Metode:
  • GET za dohvaćanje podataka (status poruke, stanje itd.)
  • POST za stvaranje objekata (npr. pokretanje emitiranja/odpreme)
  • PATCH za izmjenu objekata

2. Ovlaštenje

Za vašu udobnost nudimo nekoliko metoda autorizacije: - Osnovna HTTP provjera autentičnosti (prijava i lozinka s vaše nadzorne ploče). - Prilagođeno HTTP zaglavlje X-Authorization-Key koje sadrži API token. - Polje lozinke za HTTP osnovnu provjeru autentičnosti koje sadrži API token (proslijedite @ kao prijavu).

API token se može generirati na Nadzornoj ploči pod Korisnički profil.

Primjeri zahtjeva

S osnovnom autorizacijom: 

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

U SMSBAT platformi, svaka poruka (čak i jedna poruka) smatra se "broadcastom" (messagelist).

Krajnja toč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-naziv potvrđenog pošiljatelja.
  • za: telefonski broj primatelja (format E.164).
  • type: tip poruke enum.
  • tekst: glavni tekst poruke (neobavezno ako tip ne zahtijeva tekst).

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

Neobavezna uobičajena polja:

  • customerMessageId: ID niza unutar vašeg vlastitog sustava (koristi se za praćenje povratnih poziva). Mora biti jedinstven po poruci.
  • dtSend: ISO8601 datum/vrijeme planirane buduće otpreme.
  • dtExpire: ISO8601 datum/vrijeme roka isporuke.
  • ttl: Vrijeme do života u sekundama. (Ako dtExpire nije naveden, API izračunava preslikavanje zadanih vrijednosti iz type).

Zadani TTL (sekunde):

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

4. Zamjensko usmjeravanje (kaskadno)

Možete navesti zamjenski red čekanja kako biste osigurali isporuku poruka 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"
        }
      ]
    }
  ]
}
Rezervni se pokreću kada davatelj odbije glavnu poruku ili kada TTL istekne.

5. Pregled vrsta poruka i podataka poruka

Složene vrste poruka zahtijevaju dodatne konfiguracije umetnute u svojstvo messageData.

5.1 Viber promocija (viber_promo)

Samo slika 

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

Tekst + gumb 

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

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

Video opterećenje: 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(Također možete kombinirati Video svojstva s buttonText i buttonAction).

5.2 Viber Transactional / Service (viber_trans, viber_service)

Ako imate odobreni predložak koji sadrži priloženu datoteku: 

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

Zahtijeva polje carousel.items unutar messageData.

Ograničenja: - Dužina predmeta: između 2 i 5 predmeta - 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/popis (viber_survey)

Stvara interaktivnu anketu unutar prikaza chata. 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
Svojstvo text poruke služi kao naslov ankete (maksimalno 85 znakova). Možete proći između 2 i 5 opcija, svaka ima najviše 50 znakova.

5.5 Viber OTP (viber_otp)

Globalno koristi predregistrirane lokalizirane Viber predloške. 

"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 jezične varijante ISO koda (EN, ES, RU, TR, UK, itd.).

5.6 Brzi poziv (flashcall)

Zadnje znamenke broja za biranje (generirani kod) moraju se proslijediti preko parametra text. Ako je tekst izostavljen, kod je nasumičan i morate ga izdvojiti iz API-jevog sinkronog tijela odgovora 200 OK (poruke/tekst).

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