Pāriet uz saturu

SMSBAT RESTful API rokasgrāmata

Pilnīga SMSBAT RESTful API rokasgrāmata — viss, kas jums jāzina.

Pēdējoreiz atjaunināts: 2025. gada 29. augustā

SMSBAT RESTful API ļauj nosūtīt dažādu veidu ziņojumus: Viber-karuselis, Viber-aptauja, Viber-promo (attēli, video), Viber biznesa tērzēšana, OTP ziņojumi (Viber OTP, Flash Call) un to rezerves varianti.

Piezīme: šī ir vienotā HTTP API izejošajai ziņojumapmaiņai. Ja jums nepieciešama integrācija ar ienākošajiem robotiem (Viber Bot / Telegram Bot), lūdzu, skatiet Cascade API.

1. Protokols

  • Protokols: HTTPS
  • Pieprasījuma pamatteksts: JSON objekts, kas satur "ziņojumu" masīvu.
  • Metodes: - “GET”, lai iegūtu datus (ziņojuma statusu, atlikumu utt.) - POST, lai izveidotu objektus (piem., lai sāktu apraidi/nosūtīšanu)
  • PATCH, lai modificētu objektus

2. Autorizācija

Jūsu ērtībām mēs piedāvājam vairākas autorizācijas metodes: - HTTP pamata autentifikācija (pieteikšanās vārds un parole no jūsu informācijas paneļa). - Pielāgota HTTP galvene "X-Authorization-Key", kas satur API pilnvaru. - HTTP pamata autentifikācijas paroles lauks ar API pilnvaru (norādiet @ kā pieteikumvārdu).

API pilnvaru var ģenerēt informācijas paneļa sadaļā Lietotāja profils.

Pieprasiet piemērus

Ar pamata autentifikāciju: 

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

Ar "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. Ziņu sūtīšana

SMSBAT platformā jebkura ziņojuma nosūtīšana (pat viena ziņa) tiek uzskatīta par "Broadcast" (ziņu sarakstu).

Beigu punkts - Metode: POST - URL: https://api.smsbat.com/bat/messagelist - Galvenes: "Satura veids: lietojumprogramma/json".

Pamata kravnesības struktūra: 

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

Obligātie lauki katram ziņojuma objektam:

  • No: verificēts sūtītāja alfa nosaukums.
  • "Kam": adresāta tālruņa numurs (E.164 formāts).
  • Tips: ziņojuma veida enum.
  • "teksts": ziņojuma galvenais teksts (neobligāti, ja veidam nav nepieciešams teksts).

Atbalstītās “tipa” vērtības: - sms - "viber_service" (vai "viber_trans") - viber_promo - "viber_carousel". - "viber_survey". - viber_otp - "viber_session". - "flashcall_callback". - "zibatmiņas zvans".

Izvēles kopējie lauki:

  • "customerMessageId": virknes ID jūsu sistēmā (izmanto atzvanīšanas izsekošanai). Katram ziņojumam ir jābūt unikālam.
  • "dtSend": ISO8601 plānotās turpmākās nosūtīšanas datums/laiks.
  • "dtExpire": ISO8601 piegādes termiņa datums/laiks.
  • ttl: dzīves ilgums sekundēs. (Ja `dtExpire' nav nodrošināts, API aprēķina noklusējuma kartēšanu no "tipa").

Noklusējuma TTL (sekundēs):

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

4. Rezerves maršrutēšana (kaskādes)

Varat norādīt atkāpšanās rindu, lai nodrošinātu ziņojumu piegādi, ja primārais kanāls neizdodas vai beidzas derīguma termiņš.

{
  "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"
        }
      ]
    }
  ]
}
Atkāpšanās tiek aktivizēta, kad pakalpojumu sniedzējs noraida galveno ziņojumu vai kad beidzas TTL.

5. Pārskats par ziņojumu veidiem un ziņojuma datiem

Sarežģītiem ziņojumu veidiem ir nepieciešamas papildu konfigurācijas, kas jāievada rekvizītā “messageData”.

5.1 Viber Promo (viber_promo)

Tikai attēls 

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

Teksts + poga 

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

Attēls + teksts + poga Apvieno "img", "buttonText" un "buttonAction".

Video slodze: 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(Varat arī apvienot video rekvizītus ar 'buttonText' un 'buttonAction').

5.2. Viber darījums/pakalpojums ("viber_trans", "viber_service")

Ja jums ir apstiprināta veidne ar pievienotu failu: 

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

Nepieciešams masīvs "carousel.items" sadaļā "messageData".

Ierobežojumi: - Preču garums: no 2 līdz 5 priekšmetiem - Virsraksts: no 2 līdz 38 rakstzīmēm - ImageUrl: ieteicamais JPEG/PNG izmērs 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 Viber aptauja/saraksts (viber_survey)

Tērzēšanas skatā izveido interaktīvu aptauju. 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
Ziņojuma rekvizīts "text" darbojas kā aptaujas nosaukums (maks. 85 rakstzīmes). Varat iziet no 2 līdz 5 opcijām, katrā ne vairāk kā 50 rakstzīmes.

5.5 Viber OTP (viber_otp)

Izmanto iepriekš reģistrētas lokalizētas Viber veidnes visā pasaulē. 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
Veidnes parametri ("pin", "business_platform_name") ir stingri reģistrjutīgi. API atbalsta dažādus ISO koda valodu variantus ("EN", "ES", "RU", "TR", "UK" utt.).

5.6. zibzvans (zibzvans)

Sastādīšanas numura pēdējie cipari (ģenerētais kods) ir jānodod, izmantojot parametru "text". Ja teksts ir izlaists, kods tiek nejauši izvēlēts, un jums tas ir jāizņem no API sinhronās atbildes 200 OK atbildes pamatteksta (ziņojumi/teksts).

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