Kalo te përmbajtja

Udhëzues SMSBAT RESTful API

Udhëzues i plotë për SMSBAT RESTful API – gjithçka që duhet të dini.

Përditësimi i fundit: 29 gusht 2025

SMSBAT RESTful API ju lejon të dërgoni lloje të ndryshme mesazhesh: Viber-carousel, Viber-survey, Viber-promo (imazhe, video), biseda biznesi Viber, mesazhe OTP (Viber OTP, Flash Call) dhe variantet e tyre rezervë.

Shënim: Ky është API i unifikuar HTTP për mesazhet dalëse. Nëse keni nevojë për integrime me bots hyrëse (Viber Bot / Telegram Bot), ju lutemi referojuni Cascade API.

1. Protokolli

  • Protokolli: HTTPS
  • Trupi i kërkesës: objekt JSON që përmban një grup "mesazhesh".
  • Metodat:
  • MERR për të marrë të dhëna (statusi i mesazhit, balanca, etj.)
  • POST për të krijuar objekte (p.sh., fillimi i një transmetimi/transmetimi)
  • PATCH për të modifikuar objektet

2. Autorizimi

Ne ofrojmë disa metoda autorizimi për lehtësinë tuaj: - Autentifikimi bazë HTTP (hyrja dhe fjalëkalimi nga paneli juaj). - Kreu i personalizuar HTTP 'X-Authorization-Key' që përmban një Token API. - Fusha e fjalëkalimit të vërtetimit bazë HTTP që mban Tokenin API (kaloni @ si hyrje).

Token API mund të gjenerohet në panelin e kontrollit nën Profili i përdoruesit.

Kërkoni shembuj

Me autorizimin bazë: 

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

Me 'X-Authorization-Key': KODI_BLOCK_1

3. Dërgimi i mesazheve

Në platformën SMSBAT, çdo dërgim mesazhi (qoftë edhe një mesazh i vetëm) konsiderohet si "Transmetim" (listë mesazhesh).

Pika e fundit - Metoda: POST - URL: https://api.smsbat.com/bat/messagelist - Headers: Lloji i përmbajtjes: aplikacion/json

Struktura bazë e ngarkesës: 

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

Fushat e kërkuara për çdo objekt mesazhi:

  • nga: Emri alfa i verifikuar i dërguesit.
  • to: Numri i telefonit të marrësit (format E.164).
  • type: Lloji i mesazhit enum.
  • tekst: Teksti kryesor i mesazhit (opsionale nëse lloji nuk kërkon tekst).

Vlerat e "llojit" të mbështetur: - sms - "viber_service" (ose "viber_trans") - viber_promo - viber_carousel - viber_survey - viber_otp - viber_sesion - flashcall_callback - flashcall

Fushat e zakonshme opsionale:

  • customerMessageId: ID e vargut brenda sistemit tuaj (përdoret për ndjekjen e kthimeve të thirrjeve). Duhet të jetë unik për mesazh.
  • dtSend: ISO8601 Data/Koha e dërgimit të planifikuar në të ardhmen.
  • dtExpire: ISO8601 Data/Koha e afatit të dorëzimit.
  • ttl: Koha për të jetuar në sekonda. (Nëse "dtExpire" nuk ofrohet, API llogarit hartën e parazgjedhjeve nga "lloji").

TTL-të e paracaktuara (sekonda):

  • sms - 86400 (24 orë)
  • viber_trans / viber_service - 345600
  • viber_promo - 604800
  • viber_sesion - 604800

4. Drejtimi mbrapsht (kaskadë)

Mund të specifikoni një radhë kthimi për të siguruar dërgimin e mesazhit nëse kanali kryesor dështon ose skadon.

KODI_BLOCK_3 Rikthimet aktivizohen kur ofruesi refuzon mesazhin kryesor ose kur TTL skadon.

5. Pasqyrë e llojeve të mesazheve dhe të dhënave të mesazheve

Llojet komplekse të mesazheve kërkojnë konfigurime shtesë të injektuara në veçorinë messageData.

5.1 Viber Promo (viber_promo)

Vetëm imazh 

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

**Tekst + Butoni ** 

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

**Imazhi + Teksti + Butoni ** Kombinon "img", "buttonText" dhe "buttonAction".

Ngarkesa e videos: 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(Mund të kombinoni gjithashtu vetitë e videos me "buttonText" dhe "buttonAction").

5.2 Transaksioni / Shërbimi Viber ("viber_trans", "viber_service")

Nëse keni një shabllon të miratuar që përmban një skedar të bashkangjitur: 

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

Kërkon një grup "carousel.items" brenda "messageData".

Kufizimet: - Gjatësia e artikujve: midis 2 dhe 5 artikuj - Titulli: 2 deri në 38 karaktere - imageUrl: Madhësia e rekomanduar 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 / Lista e Viber ('viber_survey')

Krijon një sondazh interaktiv brenda pamjes së bisedës. 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
Vetia tekst e mesazhit vepron si titulli i sondazhit (maksimumi 85 karaktere). Mund të kaloni midis 2 dhe 5 opsioneve, secila maksimum 50 karaktere.

5.5 Viber OTP ("viber_otp")

Përdor modele të lokalizuara të Viber të para-regjistruar globalisht. 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
Parametrat e shabllonit (pin, emri_platformës_biznesit) janë rreptësisht të ndjeshme ndaj shkronjave të vogla. API mbështet variante të ndryshme të gjuhës së kodit ISO (EN, ES, RU, TR, UK, etj.).

5.6 Thirrje flash ("flashcall")

Shifrat e fundit të numrit të telefonimit (kodi i gjeneruar) duhet të kalohen përmes parametrit "tekst". Nëse "teksti" hiqet, kodi është i rastësishëm dhe ju duhet ta nxirrni atë nga trupi sinkron i përgjigjes 200 OK i API ("mesazhe/tekst").

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