Hyppää sisältöön

SMSBAT RESTful API Guide

Täydellinen opas SMSBAT RESTful API -sovellukseen – kaikki mitä sinun tarvitsee tietää.

Viimeksi päivitetty: 29. elokuuta 2025

SMSBAT RESTful API mahdollistaa erilaisten viestityyppien lähettämisen: Viber-karuselli, Viber-kysely, Viber-promo (kuvat, video), Viber-yrityskeskustelut, OTP-viestit (Viber OTP, Flash Call) ja niiden varaversiot.

Huomaa: Tämä on yhtenäinen HTTP API lähtevään viestiin. Jos tarvitset integraatioita saapuvien bottien (Viber Bot / Telegram Bot) kanssa, katso Cascade API.

1. Protokolla

  • Protokolla: HTTPS
  • Request Body: JSON-objekti, joka sisältää joukon "viestejä".
  • Menetelmät:
  • "GET" tietojen hakemiseen (viestin tila, saldo jne.)
  • "POST" objektien luomiseen (esim. lähetyksen/lähetyksen aloittamiseen)
  • "PATCH" objektien muokkaamiseen

2. Valtuutus

Tarjoamme useita valtuutusmenetelmiä avuksesi: - HTTP-perustodennus (kirjautumistunnus ja salasana kojelaudalta). - Muokattu HTTP-otsikko "X-Authorization-Key", joka sisältää API-tunnuksen. - HTTP Basic Authentication -salasanakenttä, jossa on API Token (syötä @ kirjautumistunnukseksi).

API Token voidaan luoda Dashboardin kohdassa Käyttäjäprofiili.

Pyydä esimerkkejä

Basic Authilla: 

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

"X-Authorization-Key" -avaimella: 

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. Viestien lähettäminen

SMSBAT-alustalla mikä tahansa viestilähetys (jopa yksittäinen viesti) katsotaan "Broadcastiksi" (viestiluetteloksi).

päätepiste - Menetelmä: POST - URL: https://api.smsbat.com/bat/messagelist - Ylätunnisteet: "Sisältötyyppi: sovellus/json".

Perushyötykuormarakenne: 

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

Pakolliset kentät jokaiselle viestiobjektille:

  • Lähettäjä: Vahvistetun lähettäjän alfa-nimi.
  • Vastaanottaja: Vastaanottajan puhelinnumero (E.164-muoto).
  • type: Viestityypin enum.
  • teksti: Viestin pääteksti (valinnainen, jos tyyppi ei vaadi tekstiä).

Tuetut tyyppiarvot: - "sms". - "viber_service" (tai "viber_trans") - "viber_promo". - "viber_carousel". - "viber_survey". - viber_otp - "viber_session". - "flashcall_callback". - "flashcall".

Valinnaiset yhteiset kentät:

  • customerMessageId: merkkijonotunnus omassa järjestelmässäsi (käytetään takaisinsoittojen seurantaan). Viestiä kohden on oltava yksilöllinen.
  • dtSend: ISO8601 Suunnitellun tulevan lähetyksen päivämäärä/aika.
  • "dtExpire": ISO8601 toimitusmääräajan päivämäärä/aika.
  • ttl: Elämisaika sekunneissa. (Jos "dtExpire" ei ole annettu, API laskee oletuskartoituksen "type" perusteella).

Oletus-TTL:t (sekunteina):

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

4. Varareititys (Cascading)

Voit määrittää varajonon varmistaaksesi viestien toimituksen, jos ensisijainen kanava epäonnistuu tai vanhenee.

{
  "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"
        }
      ]
    }
  ]
}
Varatoimitus käynnistyy, kun palveluntarjoaja hylkää pääviestin tai kun TTL vanhenee.

5. Yleiskatsaus viestityyppeihin ja viestitietoihin

Monimutkaiset viestityypit vaativat lisämäärityksiä "messageData"-ominaisuuteen.

5.1 Viber Promo (viber_promo)

Vain kuva 

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

Teksti + painike 

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

Kuva + teksti + painike Yhdistää sanat "img", "buttonText" ja "buttonAction".

Videon hyötykuorma: 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(Voit myös yhdistää videon ominaisuudet "buttonText"- ja "buttonAction"-toimintoihin).

5.2 Viber Transaction / Service (viber_trans, viber_service)

Jos sinulla on hyväksytty malli, joka sisältää liitteenä olevan tiedoston: 

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

Vaatii carousel.items-taulukon viestin "messageData" sisällä.

Rajoitukset: - Tuotteiden pituus: 2-5 tuotetta - Otsikko: 2–38 merkkiä - "imageUrl": JPEG/PNG-suosituskoko 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 / List (viber_survey)

Luo interaktiivisen kyselyn chat-näkymään. 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
Viestin teksti-ominaisuus toimii kyselyn otsikona (enintään 85 merkkiä). Voit antaa 2–5 vaihtoehtoa, joista kukin enintään 50 merkkiä.

5.5 Viber OTP (viber_otp)

Käyttää ennalta rekisteröityjä lokalisoituja Viber-malleja maailmanlaajuisesti. 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
Mallin parametrit ("pin", "business_platform_name") ovat tiukasti kirjainkokoisia. API tukee erilaisia ​​ISO-koodikieliversioita ("EN", "ES", "RU", "TR", "UK" jne.).

5.6 Flash Call ("flashcall")

Valintanumeron (luodun koodin) viimeiset numerot on välitettävä "text"-parametrin kautta. Jos "teksti" jätetään pois, koodi satunnaistetaan ja sinun on purettava se API:n synkronisesta 200 OK-vastauksen rungosta ("viestit/teksti").

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