Kihagyás

SMSBAT RESTful API útmutató

Teljes útmutató az SMSBAT RESTful API-hoz – minden, amit tudnia kell.

Utolsó frissítés: 2025. augusztus 29.

Az SMSBAT RESTful API lehetővé teszi különböző típusú üzenetek küldését: Viber-körhinta, Viber-felmérés, Viber-promo (képek, videó), Viber üzleti chat-ek, OTP-üzenetek (Viber OTP, Flash Call) és ezek tartalék változatai.

Megjegyzés: Ez az egységes HTTP API a kimenő üzenetküldéshez. Ha integrációra van szüksége a bejövő robotokkal (Viber Bot / Telegram Bot), kérjük, tekintse meg a Cascade API-t.

1. Protokoll

  • Protokoll: HTTPS
  • Request Body: JSON-objektum, amely "üzenetek" tömbjét tartalmazza.
  • Módszerek:
  • "GET" az adatok lekéréséhez (üzenet állapota, egyenleg stb.)
  • "POST" objektumok létrehozásához (pl. sugárzás/küldés kezdeményezése)
  • PATCH az objektumok módosításához

2. Engedélyezés

Számos engedélyezési módot biztosítunk az Ön kényelme érdekében: - HTTP alapszintű hitelesítés (bejelentkezés és jelszó az irányítópultról). - Egyéni HTTP fejléc X-Authorization-Key, amely API-token-t tartalmaz. - Az alapszintű HTTP-hitelesítési jelszómező tartalmazza az API tokent (jelként adja meg a @ jelet).

Az API-token az irányítópulton, a Felhasználói profil alatt generálható.

Kérjen példákat

Alapszintű hitelesítéssel: 

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

Az "X-Authorization-Key"-vel: 

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. Üzenetek küldése

Az SMSBAT platformon minden üzenetküldés (akár egyetlen üzenet is) "Broadcast"-nak (üzenetlistának) minősül.

Végpont - Módszer: POST - URL: https://api.smsbat.com/bat/messagelist - Fejlécek: "Tartalomtípus: alkalmazás/json".

Alap rakományszerkezet: 

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

Kötelező mezők minden üzenetobjektumhoz:

  • feladó: Ellenőrzött feladó alfa-név.
  • "Címzett": A címzett telefonszáma (E.164 formátum).
  • type: Üzenettípus enum.
  • "szöveg": Az üzenet fő szövege (opcionális, ha a típus nem igényel szöveget).

Támogatott "típus" értékek: - "sms". - "viber_service" (vagy "viber_trans") - "viber_promo". - "viber_carousel". - "viber_survey". - viber_otp - viber_session - "flashcall_callback". - "flashhívás".

Választható közös mezők:

  • customerMessageId: Karakterlánc-azonosító a saját rendszerében (a visszahívások nyomon követésére szolgál). Üzenetenként egyedinek kell lennie.
  • "dtSend": ISO8601 A tervezett jövőbeli feladás dátuma/időpontja.
  • "dtExpire": ISO8601 A szállítási határidő dátuma/időpontja.
  • ttl: Élettartam másodpercekben. (Ha a „dtExpire” nincs megadva, az API a „type” alapján számítja ki az alapértelmezett leképezést.)

Alapértelmezett TTL-ek (másodperc):

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

4. Tartalék útválasztás (lépcsőzetes)

Megadhat egy tartalék sort az üzenetek kézbesítésének biztosítására, ha az elsődleges csatorna meghiúsul vagy lejár.

{
  "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"
        }
      ]
    }
  ]
}
A tartalékok akkor aktiválódnak, amikor a szolgáltató elutasítja a fő üzenetet, vagy amikor a TTL lejár.

5. Az üzenettípusok és az üzenetadatok áttekintése

Az összetett üzenettípusok további konfigurációkat igényelnek a "messageData" tulajdonságba.

5.1 Viber Promo (viber_promo)

Csak kép 

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

Szöveg + gomb 

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

Kép + szöveg + gomb Egyesíti az "img", "buttonText" és "buttonAction" kifejezéseket.

Videó terhelhetősége: 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(A Videó tulajdonságait a "buttonText" és a "buttonAction" paraméterekkel is kombinálhatja.).

5.2 Viber-tranzakció/szolgáltatás ("viber_trans", "viber_szolgáltatás")

Ha rendelkezik egy jóváhagyott sablonnal, amely csatolt fájlt tartalmaz: 

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

Szükséges egy carousel.items tömb az messageData-ban.

Korlátozások: - A tételek hossza: 2 és 5 darab között - Cím: 2-38 karakter - "imageUrl": JPEG/PNG ajánlott méret 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 felmérés / lista (viber_survey)

Interaktív szavazást hoz létre a csevegési nézetben. 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
Az üzenet "text" tulajdonsága a felmérés címeként működik (maximum 85 karakter). 2 és 5 között lehet átadni, egyenként legfeljebb 50 karakterből.

5.5 Viber OTP (viber_otp)

Előre regisztrált lokalizált Viber-sablonokat használ globálisan. 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
A sablonparaméterek ("pin", "business_platform_name") szigorúan megkülönböztetik a kis- és nagybetűket. Az API különféle ISO kódnyelvi változatokat támogat ("EN", "ES", "RU", "TR", "UK" stb.).

5.6 Flash Call ("flashcall")

A hívószám utolsó számjegyeit (a generált kódot) a "text" paraméteren keresztül kell átadni. Ha a "szöveg" kimarad, a kód véletlenszerűvé válik, és ki kell bontania az API szinkron 200 OK választörzséből ("üzenetek/szöveg").

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