SMSBAT RESTful API juhend

SMSBAT RESTful API täielik juhend – kõik, mida pead teadma.

Viimati värskendatud: 29. august 2025

SMSBAT RESTful API võimaldab saata erinevat tüüpi sõnumeid: Viber-karussell, Viber-küsitlus, Viber-promo (pildid, video), Viberi ärivestlused, OTP-sõnumid (Viber OTP, Flash Call) ja nende varuvariandid.

Märkus: see on ühtne HTTP API väljaminevate sõnumite jaoks. Kui vajate integreerimist sissetulevate robotitega (Viber Bot / Telegram Bot), vaadake Cascade API-t.

---

1. Protokoll

• Protokoll: HTTPS
• Request Body: JSON-objekt, mis sisaldab sõnumite massiivi.
• Meetodid:
• "GET" andmete toomiseks (sõnumi olek, saldo jne)
• "POSTITUS" objektide loomiseks (nt edastuse/saatmise algatamine)
• "PATCH" objektide muutmiseks

2. Autoriseerimine

Pakume teie mugavuse huvides mitmeid autoriseerimismeetodeid: - HTTP põhiautentimine (sisselogimine ja parool teie armatuurlaualt). - Kohandatud HTTP päis "X-Authorization-Key", mis sisaldab API tunnust. - HTTP põhiautentimise parooliväli, millel on API tunnus (sisselogimiseks sisestage @).

API märgi saab luua juhtpaneeli jaotises Kasutajaprofiil.

Taotlege näiteid

Põhiautentimisega:

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

X-Authorization-Keyga:

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. Sõnumite saatmine

SMSBAT platvormis loetakse mis tahes sõnumite saatmine (isegi üks sõnum) "Broadcastiks" (sõnumiloendiks).

Lõpp-punkt - Meetod: POSTITUS - URL: https://api.smsbat.com/bat/messagelist - Päised: "Sisutüüp: rakendus/json".

Kasuliku koormuse põhistruktuur:

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

Iga sõnumiobjekti kohustuslikud väljad:

• "from": kinnitatud saatja alfa-nimi.
• "To": saaja telefoninumber (vorming E.164).
• "tüüp": sõnumi tüübi loend.
• "tekst": sõnumi põhitekst (valikuline, kui tüüp ei nõua teksti).

Toetatud tüübi väärtused: - "sms". - "viber_service" (või "viber_trans") - "viber_promo". - "viber_karussell". - "viber_survey". - "viber_otp". - "viber_session". - "flashcall_callback". - välkkõne

Valikulised üldväljad:

• „customerMessageId”: stringi ID teie enda süsteemis (kasutatakse tagasihelistamiste jälgimiseks). Sõnumi kohta peab olema kordumatu.
• "dtSend": ISO8601 kavandatud tulevase lähetamise kuupäev/kellaaeg.
• "dtExpire": ISO8601 tarnetähtaja kuupäev/kellaaeg.
• "ttl": elamisaeg sekundites. (Kui parameetrit „dtExpire” ei pakuta, arvutab API vaikevaardumise tüübi „tüüp” põhjal).

Vaike-TTL-id (sekundites):

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

---

4. Varumarsruutimine (kaskaad)

Saate määrata varujärjekorra, et tagada sõnumite edastamine, kui esmane kanal ebaõnnestub või aegub.

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

Varud käivituvad, kui pakkuja lükkab põhisõnumi tagasi või kui TTL aegub.

---

5. Ülevaade sõnumitüüpidest ja sõnumiandmetest

Keerulised sõnumitüübid nõuavad atribuudile „messageData” sisestatud lisakonfiguratsioone.

5.1 Viber Promo (viber_promo)

Ainult pilt

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

Tekst + nupp

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

Pilt + tekst + nupp Kombineerib "img", "buttonText" ja "buttonAction".

Video koormus:

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

(Saate ühendada ka video atribuudid funktsioonidega "buttonText" ja "buttonAction").

---

5.2 Viberi tehing / teenus ("viber_trans", "viber_service")

Kui teil on kinnitatud mall, mis sisaldab manustatud faili:

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

---

5.3 Viberi karussell ("viber_carousel")

Nõuab massiivi "carousel.items" üksuse "messageData" sees.

Piirangud: - Kauba pikkus: 2 kuni 5 eset - Pealkiri: 2 kuni 38 tähemärki - „imageUrl”: JPEG/PNG soovitatav suurus 215 x 185

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

---

5.4 Viberi uuring/loend (viber_survey)

Loob vestlusvaates interaktiivse küsitluse.

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

Sõnumi atribuut "text" toimib küsitluse pealkirjana (max 85 tähemärki). Saate edastada 2–5 valikut, igaüks kuni 50 tähemärki.

---

5.5 Viberi OTP (viber_otp)

Kasutab globaalselt eelregistreeritud lokaliseeritud Viberi malle.

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

Malli parameetrid ("pin", "business_platform_name") on tõstutundlikud. API toetab erinevaid ISO koodide keelevariante (EN, ES, RU, TR, UK jne).

---

5.6 välkkõne ("flashcall")

Valimisnumbri viimased numbrid (genereeritud kood) tuleb edastada parameetri "text" kaudu. Kui tekst on välja jäetud, määratakse kood juhuslikult ja peate selle API sünkroonsest 200 OK vastuse kehast (sõnumid/tekst) ekstraheerima.

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