I-skip tungo sa nilalaman

SMSBAT RESTful API Guide

Kumpletong gabay sa SMSBAT RESTful API - lahat ng kailangan mong malaman.

Huling na-update: Agosto 29, 2025

Binibigyang-daan ka ng SMSBAT RESTful API na magpadala ng iba't ibang uri ng mensahe: Viber-carousel, Viber-survey, Viber-promo (mga larawan, video), Viber business chat, OTP na mensahe (Viber OTP, Flash Call), at ang kanilang mga fallback na variant.

Tandaan: Ito ang pinag-isang HTTP API para sa papalabas na pagmemensahe. Kung kailangan mo ng mga pagsasama sa mga papasok na bot (Viber Bot / Telegram Bot), mangyaring sumangguni sa Cascade API.

1. Protocol

  • Protocol: HTTPS
  • Katawan ng Kahilingan: JSON object na naglalaman ng array ng mensahe.
  • Mga Paraan:
  • GET para kumuha ng data (status ng mensahe, balanse, atbp.)
  • POST para gumawa ng mga bagay (hal., pagsisimula ng broadcast/dispatch)
  • PATCH upang baguhin ang mga bagay

2. Awtorisasyon

Nagbibigay kami ng ilang paraan ng pagpapahintulot para sa iyong kaginhawahan: - HTTP Basic Authentication (pag-login at password mula sa iyong dashboard). - Custom na HTTP Header X-Authorization-Key na naglalaman ng API Token. - HTTP Basic Authentication password field na may hawak na API Token (ipasa ang @ bilang login).

API Token ay maaaring mabuo sa Dashboard sa ilalim ng User Profile.

Humiling ng mga Halimbawa

Gamit ang Basic Auth: 

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

Gamit ang 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. Pagpapadala ng mga Mensahe

Sa platform ng SMSBAT, ang anumang pagpapadala ng mensahe (kahit isang mensahe) ay itinuturing na isang "Broadcast" (messagelist).

Endpoint - Paraan: POST - URL: https://api.smsbat.com/bat/messagelist - Mga Header: Uri ng Nilalaman: application/json

Basic Payload Structure: 

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

Mga Kinakailangang Field para sa Bawat Bagay ng Mensahe:

  • from: Na-verify na nagpadala ng alpha-name.
  • to: Numero ng telepono ng tatanggap (E.164 format).
  • type: Message type enum.
  • teksto: Pangunahing teksto ng mensahe (opsyonal kung ang uri ay hindi nangangailangan ng teksto).

Mga Suportadong type na Value: - sms - viber_service (o viber_trans) - viber_promo - viber_carousel - viber_survey - viber_otp - viber_session - flashcall_callback - flashcall

Opsyonal na Mga Karaniwang Patlang:

  • customerMessageId: String ID sa loob ng sarili mong system (ginagamit para sa pagsubaybay sa mga callback). Dapat na natatangi bawat mensahe.
  • dtSend: ISO8601 Petsa/Oras ng naka-iskedyul na pagpapadala sa hinaharap.
  • dtExpire: ISO8601 Petsa/Oras ng deadline ng paghahatid.
  • ttl: Time-To-Live sa ilang segundo. (Kung hindi ibinigay ang dtExpire, kinakalkula ng API ang mga default na pagmamapa mula sa type).

Mga Default na TTL (Segundo):

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

4. Fallback Routing (Cascading)

Maaari kang tumukoy ng fallback queue upang matiyak ang paghahatid ng mensahe kung nabigo o mag-expire ang pangunahing channel.

{
  "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"
        }
      ]
    }
  ]
}
Nagti-trigger ang mga fallback kapag tinanggihan ng provider ang pangunahing mensahe o kapag nag-expire ang TTL.

5. Pangkalahatang-ideya ng Mga Uri ng Mensahe at messageData

Ang mga kumplikadong uri ng mensahe ay nangangailangan ng mga karagdagang configuration na ini-inject sa property na messageData.

5.1 Viber Promo (viber_promo)

Larawan Lamang 

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

Text + Button 

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

Larawan + Teksto + Button Pinagsasama ang img, buttonText, at buttonAction.

Video Payload: 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(Maaari mo ring pagsamahin ang mga katangian ng Video sa buttonText at buttonAction).

5.2 Viber Transactional / Serbisyo (viber_trans, viber_service)

Kung mayroon kang naaprubahang template na naglalaman ng naka-attach na file: 

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

Nangangailangan ng hanay ng carousel.items sa loob ng messageData.

Mga Limitasyon: - Haba ng mga item: sa pagitan ng 2 at 5 item - Pamagat: 2 hanggang 38 character - imageUrl: JPEG/PNG inirerekomendang laki 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 Survey / Listahan (viber_survey)

Lumilikha ng interactive na poll sa loob ng chat view. 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
Ang text na pag-aari ng mensahe ay nagsisilbing pamagat ng survey (Max 85 chars). Maaari kang pumasa sa pagitan ng 2 at 5 opsyon, bawat isa ay max 50 char.

5.5 Viber OTP (viber_otp)

Gumagamit ng paunang rehistradong naka-localize na mga template ng Viber sa buong mundo. 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
Ang mga parameter ng template (pin, business_platform_name) ay mahigpit na case-sensitive. Sinusuportahan ng API ang iba't ibang variant ng wika ng ISO code (EN, ES, RU, TR, UK, atbp.).

5.6 Flash Call (flashcall)

Ang mga huling digit ng numero ng pag-dial (ang nabuong code) ay dapat na maipasa sa pamamagitan ng parameter na text. Kung aalisin ang text, randomized ang code at dapat mong i-extract ito mula sa naka-synchronous na 200 OK Response body ng API (messages/text).

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