Перейти до змісту

Посібник з SMSBAT RESTful API

Повний посібник із SMSBAT RESTful API – усе, що вам потрібно знати.

Оновлено: 29 серпня 2025 року

SMSBAT RESTful API дозволяє надсилати повідомлення різних типів: Viber-карусель, Viber-опитування, Viber-промо (зображення, відео), Viber бізнес-чати, OTP-повідомлення (Viber OTP, Flash Call) та налаштовувати резервні маршрути (fallback).

Примітка: Це уніфікований HTTP API для вихідних розсилок. Якщо вам потрібна взаємодія із вхідними ботами (Viber Bot / Telegram Bot), зверніться до документації Cascade API.

1. Протокол

  • Протокол: HTTPS
  • Тіло запиту: JSON-об'єкт, що містить масив messages.
  • Методи:
  • GET для отримання даних (перевірка статусу, перевірка балансу).
  • POST для створення об'єктів (наприклад, запуск розсилки).
  • PATCH для зміни або оновлення наявних об'єктів.

2. Авторизація

Для вашої зручності ми надаємо кілька методів авторизації: - HTTP Basic Authentication (логін і пароль з панелі керування). - Користувацький заголовок X-Authorization-Key, що містить API Токен. - Передача API Токена через HTTP Basic Authentication у полі пароля (логін у цьому випадку має бути @).

API Токен можна згенерувати в Особистому кабінеті у розділі Профіль користувача.

Приклади запитів

Через Basic Auth: 

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: 

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. Надсилання повідомлень

У системі SMSBAT будь-яке відправлення (навіть одного повідомлення) вважається "Розсилкою" (messagelist).

Ендпоінт - Метод: POST - URL: https://api.smsbat.com/bat/messagelist - Заголовки: Content-Type: application/json

Базова структура тіла запиту: 

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "text": "Перегляньте наші новинки!",
      "type": "viber_carousel",
      "ttl": 300,
      "messageData": { ... }
    }
  ]
}

Обов'язкові поля об'єкта Message:

  • from: Зареєстроване та верифіковане Альфа-ім'я відправника (бренд).
  • to: Номер телефону одержувача у міжнародному форматі (E.164).
  • type: Тип повідомлення.
  • text: Основний текст повідомлення (опціонально, якщо тип цього не вимагає).

Підтримувані типи (type): - sms - viber_service (аБО viber_trans) - viber_promo - viber_carousel - viber_survey - viber_otp - viber_session - flashcall_callback - flashcall

Додаткові параметри:

  • customerMessageId: Унікальний ID повідомлення з вашої системи (використовується для звітів).
  • dtSend: Дата/Час (ISO8601) для відкладеної розсилки.
  • dtExpire: Строк дійсности повідомлення, дата/час (ISO8601).
  • ttl: Час "життя" (Time-To-Live) в секундах. Якщо не вказано dtExpire, час життя вираховується за замовчуванням.

Замовчувані значення TTL (секунди):

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

4. Каскадна відправка (Fallback повідомлення)

Ви можете додати масив fallbacks, щоб повідомлення автоматично перемикалося на інший канал зв’язку, якщо поточний недоступний (або вичерпано ttl).

{
  "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. Огляд типів повідомлень та messageData

Складні мультимедійні повідомлення вимагають заповнення об'єкта messageData.

5.1 Viber Promo (viber_promo)

Лише зображення 

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

Текст + Кнопка 

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

Відео повідомлення: 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}

5.2 Viber Transactional (viber_trans, viber_service)

Якщо у вас є затверджений шаблон транзакційного повідомлення з прикріпленим файлом: 

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

Карусель вимагає передачі масиву carousel.items всередині messageData. Можна розмістити від 2 до 5 блоків.

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

5.4 Viber Опитування (viber_survey)

Дозволяє створити список варіантів прямо під текстом у стрічці чату. Заголовок списку задається через поле text. 

"messageData": {
  "survey": {
    "options": [
      "Відмінно", "Добре", "Нормально", "Погано"
    ]
  }
}

5.5 Viber OTP (viber_otp)

Використовує шаблонні одноразові паролі. Існує 9 глобальних стандартних шаблонів різними мовами. 

"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)

Дзвінок авторизації. Останні цифри телефонного номера (генерується код) передаються через параметр text. Якщо поле text порожнє, код генерується випадковим чином і повертається у синхронній відповіді 200 OK.

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