Vodnik za API SMSBAT RESTful

Popoln vodnik za SMSBAT RESTful API – vse, kar morate vedeti.

Nazadnje posodobljeno: 29. avgust 2025

SMSBAT RESTful API omogoča pošiljanje različnih tipov sporočil: Viber-vrtiljak, Viber-anketa, Viber-promo (slike, video), Viber poslovni klepeti, sporočila OTP (Viber OTP, Flash Call) in njihove rezervne različice.

Opomba: To je poenoten HTTP API za izhodna sporočila. Če potrebujete integracije z vhodnimi boti (Viber Bot / Telegram Bot), si oglejte Cascade API.

---

1. Protokol

• Protokol: HTTPS
• Telo zahteve: Objekt JSON, ki vsebuje niz sporočil.
• Metode:
• GET za pridobivanje podatkov (stanje sporočila, stanje itd.)
• POST za ustvarjanje objektov (npr. začetek oddajanja/pošiljanja)
• PATCH za spreminjanje predmetov

2. Pooblastilo

Za vaše udobje nudimo več načinov avtorizacije: - Osnovna avtentikacija HTTP (prijava in geslo z vaše nadzorne plošče). - Glava HTTP po meri X-Authorization-Key, ki vsebuje žeton API. - Polje za geslo za osnovno preverjanje pristnosti HTTP, ki vsebuje žeton API (podajte @ kot prijavo).

API Token lahko ustvarite na nadzorni plošči pod Uporabniški profil.

Primeri zahtev

Z osnovno avtorizacijo:

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

Z 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. Pošiljanje sporočil

V platformi SMSBAT se vsako pošiljanje sporočila (tudi posamezno sporočilo) obravnava kot "Broadcast" (messagelist).

Končna točka - Metoda: POST - URL: https://api.smsbat.com/bat/messagelist - Glave: Content-Type: application/json

Osnovna struktura tovora:

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

Zahtevana polja za vsak predmet sporočila:

• `from': alfa-ime preverjenega pošiljatelja.
• za: telefonska številka prejemnika (format E.164).
• type: tip sporočila enum.
• text: glavno besedilo sporočila (izbirno, če vrsta ne zahteva besedila).

Podprte vrednosti type: - "sms". - viber_service (ali viber_trans) - viber_promo - viber_vrtiljak - viber_anketa - viber_otp - viber_session - flashcall_callback - bliskovski klic

Izbirna pogosta polja:

• customerMessageId: ID niza znotraj vašega sistema (uporablja se za sledenje povratnim klicem). Vsako sporočilo mora biti edinstveno.
• dtSend: ISO8601 datum/čas načrtovane prihodnje odpreme.
• dtExpire: ISO8601 datum/čas roka dostave.
• ttl: Življenjska doba v sekundah. (Če dtExpire ni na voljo, API izračuna privzeto preslikavo iz type).

Privzeti TTL (sekunde):

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

---

4. Nadomestno usmerjanje (kaskadno)

Določite lahko nadomestno čakalno vrsto, da zagotovite dostavo sporočil, če primarni kanal odpove ali poteče.

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

Nadomestne možnosti se sprožijo, ko ponudnik zavrne glavno sporočilo ali ko poteče TTL.

---

5. Pregled vrst sporočil in podatkov sporočil

Zapletene vrste sporočil zahtevajo dodatne konfiguracije, vstavljene v lastnost messageData.

5.1 Viber Promo (viber_promo)

Samo slika

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

Besedilo + gumb

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

Slika + besedilo + gumb Združuje img, buttonText in buttonAction.

Koristni video:

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

(Lahko tudi kombinirate lastnosti videa z buttonText in buttonAction).

---

5.2 Viber Transactional/Storitev (viber_trans, viber_service)

Če imate odobreno predlogo s priloženo datoteko:

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

---

5.3 Viber Carousel (viber_carousel)

Zahteva matriko »carousel.items« znotraj »messageData«.

Omejitve: - Dolžina kosov: od 2 do 5 kosov - Naslov: 2 do 38 znakov - imageUrl: priporočena 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 Anketa / Seznam Viber (viber_survey)

Ustvari interaktivno anketo v pogledu klepeta.

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

Lastnost text sporočila deluje kot naslov ankete (največ 85 znakov). Posredujete lahko od 2 do 5 možnosti, vsaka ima največ 50 znakov.

---

5.5 Viber OTP (viber_otp)

Globalno uporablja vnaprej registrirane lokalizirane predloge Viber.

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

Parametri predloge (pin, business_platform_name) so strogo občutljivi na velike in male črke. API podpira različne jezikovne različice kode ISO (EN, ES, RU, TR, UK itd.).

---

5.6 Hitri klic (flashcall)

Zadnje števke klicne številke (generirana koda) je treba posredovati prek parametra text. Če je besedilo izpuščeno, je koda naključna in jo morate ekstrahirati iz sinhronega telesa odziva 200 OK API-ja (sporočila/besedilo).

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