Skip to content

SMSBAT RESTful API Gwida

Gwida kompluta għall-API RESTful SMSBAT - dak kollu li għandek bżonn tkun taf.

Aġġornata l-aħħar: 29 ta' Awwissu, 2025

SMSBAT RESTful API jippermettilek li tibgħat diversi tipi ta 'messaġġi: Viber-carousel, Viber-survey, Viber-promo (immaġini, vidjo), chats tan-negozju Viber, messaġġi OTP (Viber OTP, Flash Call), u l-varjanti ta' riżerva tagħhom.

Nota: Din hija l-API HTTP unifikata għall-messaġġi 'l barra. Jekk għandek bżonn integrazzjoni ma' bots deħlin (Viber Bot / Telegram Bot), jekk jogħġbok irreferi għall-API Cascade.

1. Protokoll

  • Protokoll: HTTPS
  • Request Body: oġġett JSON li fih firxa ta' "messaġġi".
  • Metodi:
  • GET biex iġġib id-dejta (istatus tal-messaġġ, bilanċ, eċċ.)
  • POST biex toħloq oġġetti (eż., tibda xandira/dispaċċ)
  • PATCH biex timmodifika l-oġġetti

2. Awtorizzazzjoni

Aħna nipprovdu diversi metodi ta' awtorizzazzjoni għall-konvenjenza tiegħek: - Awtentikazzjoni Bażika HTTP (login u password mid-dashboard tiegħek). - Custom HTTP Header X-Authorization-Key li fih Token API. - Il-qasam tal-password tal-Awtentikazzjoni Bażika HTTP li jżomm it-Token tal-API (għaddi @ bħala l-login).

API Token jista' jiġi ġġenerat fid-Dashboard taħt User Profile.

Talba Eżempji

B'Awtorizzazzjoni Bażika: 

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

B''X-Awtorizzazzjoni-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. Tibgħat Messaġġi

Fil-pjattaforma SMSBAT, kwalunkwe dispaċċ ta' messaġġ (anke messaġġ wieħed) jitqies bħala "Xandira" (lista ta' messaġġi).

Punt ta' tmiem - Metodu: POST - URL: https://api.smsbat.com/bat/messagelist - Headers: Content-Type: application/json

Struttura Bażika tat-Tagħbija: 

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

Oqsma Meħtieġa għal Kull Oġġett tal-Messaġġ:

  • minn: isem alfa tal-mittent ivverifikat.
  • to: Numru tat-telefon tar-riċevitur (format E.164).
  • `tip': Enum tat-tip ta' messaġġ.
  • test: Test ewlieni tal-messaġġ (mhux obbligatorju jekk it-tip ma jeħtieġx test).

Valuri tat-'tip' appoġġjati: - sms - viber_service (jew viber_trans) - viber_promo - viber_carousel - viber_survey - viber_otp - viber_session - flashcall_callback - "flashcall".

Oqsma Komuni Fakultattivi:

  • customerMessageId: String ID ġewwa s-sistema tiegħek stess (użat għat-traċċar ta' callbacks). Għandu jkun uniku għal kull messaġġ.
  • "dtSend": ISO8601 Data/Ħin tad-dispaċċ futur skedat.
  • "dtExpire": ISO8601 Data/Ħin tal-iskadenza tal-kunsinna.
  • ttl: Time-To-Live f'sekondi. (Jekk "dtExpire" ma jiġix ipprovdut, l-API tikkalkula l-immappjar tal-inadempjenzi mit-"tip").

TTLs default (Sekondi):

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

4. Rotot ta' Fallback (Cascading)

Tista' tispeċifika kju ta' riżerva biex tiżgura l-kunsinna tal-messaġġi jekk il-kanal primarju jfalli jew jiskadi.

{
  "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"
        }
      ]
    }
  ]
}
Fallbacks jibdew meta l-fornitur jiċħad il-messaġġ prinċipali jew meta jiskadi t-TTL.

5. Ħarsa ġenerali tat-Tipi tal-Messaġġ u d-Data tal-messaġġ

Tipi ta' messaġġi kumplessi jeħtieġu konfigurazzjonijiet addizzjonali injettati fil-proprjetà messageData.

5.1 Viber Promo (viber_promo)

Immaġini Biss 

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

Test + Button 

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

Immaġini + Test + Buttuna Jikkombina img, buttonText, u buttonAction.

Tagħbija tal-vidjow: 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(Tista 'wkoll tgħaqqad il-proprjetajiet tal-Vidjo ma' buttonText u buttonAction).

5.2 Viber Transazzjonali/Servizz (viber_trans, viber_service)

Jekk għandek mudell approvat li fih fajl mehmuż: 

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

Jeħtieġ firxa carousel.items ġewwa messageData.

Limitazzjonijiet: - Tul tal-oġġetti: bejn 2 u 5 oġġetti - Titolu: 2 sa 38 karattru - imageUrl: JPEG/PNG rakkomandat daqs 215x185

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

5.4 Stħarriġ / Lista Viber (viber_survey)

Joħloq stħarriġ interattiv fi ħdan il-veduta taċ-chat. 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
Il-proprjetà "test" tal-messaġġ taġixxi bħala t-titlu tal-istħarriġ (Max 85 chars). Tista 'tgħaddi bejn 2 u 5 għażliet, kull massimu ta' 50 karattri.

5.5 Viber OTP ("viber_otp")

Juża mudelli Viber lokalizzati pre-reġistrati globalment. 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
Il-parametri tal-mudell (pin, business_platform_name) huma strettament sensittivi għall-każ. L-API tappoġġja diversi varjanti tal-lingwa tal-kodiċi ISO (EN, ES, RU, TR, UK, eċċ.).

5.6 Sejħa Flash ('flashcall')

L-aħħar ċifri tan-numru ta' tisselezzjona (il-kodiċi ġġenerat) għandhom jiġu mgħoddija permezz tal-parametru "test". Jekk test titħalla barra, il-kodiċi jiġi randomised u trid estrattih mill-korp sinkroniku ta' 200 OK Response tal-API (messaġġi/test).

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