Skip to content

Ghid API RESTful SMSBAT

Ghid complet pentru API-ul SMSBAT RESTful - tot ce trebuie să știți.

Ultima actualizare: 29 august 2025

API-ul SMSBAT RESTful vă permite să trimiteți diferite tipuri de mesaje: Viber-carusel, Viber-survey, Viber-promo (imagini, video), chat-uri de afaceri Viber, mesaje OTP (Viber OTP, Flash Call) și variantele lor de rezervă.

Notă: acesta este API-ul HTTP unificat pentru mesajele de ieșire. Dacă aveți nevoie de integrări cu boți de intrare (Viber Bot / Telegram Bot), vă rugăm să consultați API-ul Cascade.

1. Protocol

  • Protocol: HTTPS
  • Request Body: obiect JSON care conține o matrice de „mesaje”.
  • Metode:
  • GET pentru a prelua date (starea mesajului, sold, etc.)
  • POST pentru a crea obiecte (de exemplu, inițierea unei difuzări/expediere)
  • PATCH pentru a modifica obiectele

2. Autorizare

Vă oferim mai multe metode de autorizare pentru confortul dvs.: - Autentificare de bază HTTP (login și parolă din tabloul de bord). - Antet HTTP personalizat X-Authorization-Key care conține un token API. - Câmp pentru parolă de autentificare de bază HTTP care conține simbolul API (treceți @ ca login).

Tokenul API poate fi generat în Tabloul de bord sub Profil utilizator.

Exemple de solicitare

Cu autentificare de bază: 

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

Cu „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. Trimiterea mesajelor

În platforma SMSBAT, orice trimitere de mesaje (chiar și un singur mesaj) este considerată „Broadcast” (listă de mesaje).

Punctul final - Metoda: POST - URL: https://api.smsbat.com/bat/messagelist - Headers: Content-Type: application/json

Structură de bază a sarcinii utile: 

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

Câmpuri obligatorii pentru fiecare obiect de mesaj:

  • from: Numele alfa al expeditorului verificat.
  • to: numărul de telefon al destinatarului (format E.164).
  • type: enumerarea tipului de mesaj.
  • text: textul principal al mesajului (opțional dacă tipul nu necesită text).

Valori tip acceptate: - sms - viber_service (sau viber_trans) - viber_promo - viber_carusel - viber_survey - viber_otp - viber_session - flashcall_callback - flashcall

Câmpuri comune opționale:

  • customerMessageId: ID-ul șirului în interiorul propriului sistem (utilizat pentru urmărirea apelurilor înapoi). Trebuie să fie unic pe mesaj.
  • dtSend: ISO8601 Data/Ora expedierii viitoare programate.
  • dtExpire: ISO8601 Data/Ora termenului limită de livrare.
  • ttl: Time-To-Live în secunde. (Dacă dtExpire nu este furnizat, API-ul calculează maparea implicită din type).

TTL implicite (secunde):

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

4. Rutare de rezervă (în cascadă)

Puteți specifica o coadă de rezervă pentru a asigura livrarea mesajelor dacă canalul principal eșuează sau expiră.

{
  "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"
        }
      ]
    }
  ]
}
Fallback-urile se declanșează atunci când furnizorul respinge mesajul principal sau când TTL expiră.

5. Prezentare generală a Tipurilor de Mesaje și Datele mesajelor

Tipurile de mesaje complexe necesită configurații suplimentare injectate în proprietatea messageData.

5.1 Promoție Viber (viber_promo)

Numai imagine 

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

Text + Buton 

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

Imagine + Text + Buton Combină img, buttonText și buttonAction.

Încărcare utilă video: 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(De asemenea, puteți combina proprietățile Video cu buttonText și buttonAction).

5.2 Viber Tranzacțional / Serviciu (viber_trans, viber_service)

Dacă aveți un șablon aprobat care conține un fișier atașat: 

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

Necesită o matrice carousel.items în interiorul messageData.

Limitări: - Lungimea articolelor: intre 2 si 5 articole - Titlu: 2 până la 38 de caractere - imageUrl: dimensiunea recomandată JPEG/PNG 215x185

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

5.4 Sondaj Viber / Listă (viber_survey)

Creează un sondaj interactiv în vizualizarea chat. 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
Proprietatea text a mesajului acționează ca titlul sondajului (Max 85 de caractere). Puteți trece între 2 și 5 opțiuni, fiecare cu maximum 50 de caractere.

5.5 Viber OTP (viber_otp)

Utilizează la nivel global șabloane Viber localizate preînregistrate. 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
Parametrii șablonului (pin, business_platform_name) sunt strict sensibile la majuscule. API-ul acceptă diverse variante de limbaj de cod ISO (EN, ES, RU, TR, UK etc.).

5.6 Apel flash (flashcall)

Ultimele cifre ale numărului de apelare (codul generat) trebuie trecute prin parametrul text. Dacă text este omis, codul este randomizat și trebuie să-l extrageți din corpul de răspuns sincron 200 OK al API-ului (mesaje/text).

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