SMSBAT RESTful API vadovas
Išsamus SMSBAT RESTful API vadovas – viskas, ką reikia žinoti.
Paskutinį kartą atnaujinta: 2025 m. rugpjūčio 29 d.
SMSBAT RESTful API leidžia siųsti įvairių tipų žinutes: Viber-karuselė, Viber-survey, Viber-promo (vaizdai, video), Viber verslo pokalbiai, OTP žinutės (Viber OTP, Flash Call) ir jų atsarginiai variantai.
Pastaba: tai vieninga HTTP API, skirta siunčiamiems pranešimams. Jei jums reikia integracijos su gaunamais robotais („Viber Bot“ / „Telegram Bot“), žr. „Cascade“ API.
1. Protokolas
– Protokolas: HTTPS – Užklausos turinys: JSON objektas, kuriame yra „pranešimų“ masyvas. - Metodai: - „GET“, kad gautumėte duomenis (pranešimo būseną, likutį ir kt.) - „POST“, kad sukurtumėte objektus (pvz., inicijuokite transliaciją / išsiuntimą) - „PATCH“ objektams modifikuoti
2. Autorizacija
Jūsų patogumui siūlome kelis autorizavimo būdus: - HTTP pagrindinis autentifikavimas (prisijungimo vardas ir slaptažodis iš jūsų prietaisų skydelio). – Tinkinta HTTP antraštė „X-Authorization-Key“ su API prieigos raktu. – HTTP pagrindinės autentifikavimo slaptažodžio laukas, kuriame yra API prieigos raktas (prisijungdami nurodykite „@“).
API prieigos raktą galima sugeneruoti informacijos suvestinės skiltyje Vartotojo profilis.
Užklausos pavyzdžiai
Su pagrindine autentifikacija:
curl -H "Content-Type: application/json" \
-X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist \
--user user:password
Su „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. Žinučių siuntimas
SMSBAT platformoje bet koks pranešimų išsiuntimas (net ir vienas pranešimas) laikomas „transliacija“ (pranešimų sąrašu).
Galinis taškas
- Metodas: PAST
– URL: https://api.smsbat.com/bat/messagelist
– Antraštės: „Turinio tipas: programa/json“.
Pagrindinė naudingosios apkrovos struktūra:
{
"messages": [
{
"from": "ALPHANAME",
"to": "380936670003",
"text": "Check out our new products!",
"type": "viber_carousel",
"ttl": 300,
"messageData": { ... }
}
]
}
Privalomi laukai kiekvienam pranešimo objektui:
- „nuo“: patvirtintas siuntėjo alfa vardas.
- „Kam“: gavėjo telefono numeris (E.164 formatas).
- Tipas: pranešimo tipo sąrašas.
- "tekstas": pagrindinis pranešimo tekstas (neprivaloma, jei tipui nereikia teksto).
Palaikomos „tipo“ reikšmės: - "sms". - „viber_service“ (arba „viber_trans“) - „viber_promo“. - "viber_carousel". - „viber_survey“. - „viber_otp“. - „viber_session“. - „flashcall_callback“. - „flashcall“.
Pasirenkami bendrieji laukai:
- „customerMessageId“: eilutės ID jūsų sistemoje (naudojamas atgaliniams skambučiams stebėti). Kiekviename pranešime turi būti unikalus.
- „dtSend“: ISO8601 suplanuoto būsimo išsiuntimo data / laikas.
- „dtExpire“: ISO8601 pristatymo termino data / laikas.
- „ttl“: laikas gyventi per kelias sekundes. (Jei „dtExpire“ nepateikta, API apskaičiuoja numatytąjį susiejimą iš „tipo“).
Numatytieji TTL (sekundėmis):
- "Sms" - 86400 (24 val.) – „viber_trans“ / „viber_service“ – 345600 – „viber_promo“ – 604800 – „viber_session“ – 604800
4. Atsarginis maršrutas (pakopinis)
Galite nurodyti atsarginę eilę, kad užtikrintumėte pranešimų pristatymą, jei pirminis kanalas sugenda arba baigiasi.
{
"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"
}
]
}
]
}
5. Pranešimų tipų ir pranešimų duomenų apžvalga
Sudėtingiems pranešimų tipams reikia papildomų konfigūracijų, įterptų į nuosavybę „messageData“.
5.1 „Viber Promo“ („viber_promo“)
Tik vaizdas
Tekstas + mygtukas
Vaizdas + tekstas + mygtukas Sujungia „img“, „buttonText“ ir „buttonAction“.
Vaizdo įrašo apkrova:
"messageData":{
"video": "https://domain.com/test.mp4",
"thumbnail": "https://domain.com/carusel.png",
"fileSize": 12000000,
"duration": 30
}
5.2 „Viber“ sandoris / paslauga („viber_trans“, „viber_service“)
Jei turite patvirtintą šabloną su pridėtu failu:
"messageData": {
"fileUrl": "https://domain.com/receipt.pdf",
"fileName": "Receipt.pdf",
"fileType": "pdf"
}
5.3 „Viber Carousel“ („viber_carousel“)
Reikalingas „carousel.items“ masyvas „messageData“ viduje.
Apribojimai: - Prekių ilgis: nuo 2 iki 5 prekių - Pavadinimas: nuo 2 iki 38 simbolių - „imageUrl“: rekomenduojamas JPEG / PNG dydis 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“ apklausa / sąrašas („viber_survey“)
Sukuria interaktyvią apklausą pokalbio rodinyje.
Pranešimo ypatybė „text“ veikia kaip apklausos pavadinimas (daugiausia 85 simboliai). Galite perduoti nuo 2 iki 5 parinkčių, kurių kiekviena yra ne daugiau kaip 50 simbolių.5.5 Viber OTP („viber_otp“)
Naudoja iš anksto užregistruotus lokalizuotus Viber šablonus visame pasaulyje.
"messageData": {
"templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
"templateLang": "uk",
"templateParams": {
"pin": "3211",
"business_platform_name": "SMSBAT",
"code_validity_time": 7
}
}
5.6 „Flash Call“ („flashcall“)
Paskutiniai rinkimo numerio skaitmenys (sugeneruotas kodas) turi būti perduodami per parametrą "tekstas". Jei „tekstas“ praleistas, kodas yra atsitiktinai suskirstytas ir jūs turite jį išskirti iš API sinchroninio 200 OK atsakymo turinio („pranešimai/tekstas“).