SMSBAT RESTful API

Повний посібник розробника

SMSBAT – це RESTful API для надсилання різних типів повідомлень: Viber‑карусель, Viber‑опитування, Viber‑промо (картинки, відео), Viber бізнес чати, OTP‑повідомлення (Viber OTP, flashcall) та їхні fallback‑варианти.

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

Огляд

Довідкова документація по SMSBAT RESTful API, яке найповніше реалізує можливості взаємодії із платформою SMSBAT. Якщо потрібна реалізація з додаванням запитів Viber Bot та/чи Telegram Bot - це доступно в посібнику SMSBAT Cascade API.

Примітка

Вартість

Про вартість та умови використання SMSBAT RESTful API та або SMSBAT Cascade API ви можете дізнатись у розділі Тарифи та оплата.

1. Протокол

Як протокол використовується HTTPS. Тіло запиту – JSON‑масив об'єктів messages.

Методи запитів

GET

Отримання даних

Статус повідомлення, баланс тощо

POST

Створення об'єктів

Наприклад створення розсилки

PATCH

Зміна об'єктів

Оновлення даних повідомлення

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

Для Вашої зручності є кілька варіантів авторизації:

Логін та пароль (HTTP Basic Authentication)

Логін та пароль ті самі, що Ви використовуєте для входу в особистий кабінет.

cURL

curl -H "Content-Type: application/json"
-X POST -d @/path/to/data.json <url_smsbat_api>/bat/messagelist
--user user:password

API-ключ в заголовку

Передача API-ключа в заголовку HTTP X-Authorization-Key. Ключ автентифікації можна створити у Особистому кабінеті у Профілі користувача.

cURL

curl -H "X-Authorization-Key: <токен_доступа>"
-H "Content-Type: application/json"
-X POST -d @/path/to/data.json <url_smsbat_api>/bat/messagelist

API-ключ як пароль

Передача API-ключа у паролі HTTP Basic Authentication (як логін при цьому потрібно використовувати символ 'at').

cURL

curl -H "Content-Type: application/json" 
-X POST -d @/path/to/data.json <url_smsbat_api>/bat/messagelist
--user @:23ebe88c0224f4f4fc0b608216e98735

Важливо

Запити до SMSBAT API передаються в endpoint з локалізацією, попередньо запитайте адресу у вашого Менеджера.

3. Надсилання повідомлень

У платформі SMSBAT будь-яке надсилання повідомлень (в т.ч. одиночних) - Розсилка. Поодиноке повідомлення - окремий випадок розсилки.

Одиночне повідомлення

Приклад надсилання одиночного повідомлення

JSON

{"messages":[
  {
    "from": "ALPHANAME",                    // ваш бренд/підпис
    "to": "380936670003",                   // номер у форматі E.164
    "type": "viber_carousel",               // тип повідомлення
    "ttl": "300",                           // Time‑To‑Live у секундах
    "text": "Погляньте на наші новинки!",   // підпис; може бути порожнім 
    "messageData": { ... }                  // специфічні поля типу
  }    
]}

Масове повідомлення

Приклад надсилання кількох повідомлень

JSON

{"messages":[
  {
    "from":"ALPHANAME",
    "to":"380936670003",
    "text":"test message",
    "type":"sms",
    "customerMessageId":"dc84a6a6-7831-11ec-968b-0025906c040e"
  },
  {
    "from":"ALPHANAME",
    "to":"380736670003",
    "text":"test message2",
    "type":"sms"
  }
]}

Параметри повідомлення

from

обов'язково

Альфаімя відправки

обов'язково

Номер одержувача у форматі E.164

text

обов'язково

Текст повідомлення (опціонально для деяких типів)

type

обов'язково

Тип повідомлення: sms, viber_service, viber_trans, viber_promo, viber_carousel, viber_survey, viber_otp, viber_session, flashcall_callback, flashcall

customerMessageId

опціонально

ID повідомлення із системи клієнта (може використовуватись для інтеграції). Має бути унікальним або не заповнюватися.

Відповідь API

Після успішного надсилання повідомлення API повертає інформацію про створену розсилку та повідомлення

JSON

{"messagelistId":11292,"messages":[
  {
    "messageId":1546807,
    "from":"ALPHANAME",
    "to":"380936670003",
    "text":"test message2",
    "dtExpire":null,
    "customerMessageId":"dc84a6a6-7831-11ec-968b-0025906c040e",
    "partsCount":1,
    "type":"viber_promo"
  }
]}

4. Статус повідомлень

Для перевірки статусу повідомлення необхідно відправити GET запит

cURL

curl -X GET https://api.smsbat.com.ua/bat/message/12345 --user user:password

4.1. Відповідь статусу

JSON

{
  "messagelistId":11229,
  "messageId":1366203,
  "deliverystatus":"delivered",
  "partscount":1,
  "cost":0.32
}

Можливі статуси

scheduled

Заплановано до відправки

processing

Відправляється

delivered

Доставлено

undeliverable

Відхилено

permanenterror

Постійна помилка відправки (повідомлення виведено з черги)

4.2. Приклад Fallback відповіді

Приклад відповіді з конфігурацією fallback

JSON

{
  "messagelistId": 49102177,
  "messageId": 90042370,
  "deliverystatus": "delivered",
  "partscount": 1,
  "cost": 0.4134,
  "fallbacks": [],
  "extendedStatuses": [],
  "partsCount": 1,
  "rate": 0.00839,
  "rateAmount": 0.00839,
  "rateCurrency": "EUR",
  "billAmount": 0.413417,
  "billCurrency": "UAH"
}

5. Особливості типів повідомлень

5.2. Тип повідомлення Viber Transactional

Тільки текст

JSON

{
  "messages":[
    {
      "from":"ALPHANAME",
      "to":"380936670003",
      "type":"viber_trans",
      "text": "Замовлення №111 вже чекає на тебе в магазині",
      "ttl": "300"
    }
  ]
}

PDF файл + текст

JSON

{
  "messages":[
    {
      "from":"ALPHANAME",
      "to":"380500000000",
      "text":"test message",
      "type":"viber_trans",
      "messageData":{
        "fileUrl":"https://domain.com/test.pdf",
        "fileName":"Test.pdf",
        "fileType":"pdf"
      }
    }
  ]
}

Тільки PDF файл

JSON

{
  "messages":[
    {
      "from":"ALPHANAME",
      "to":"380500000000",
      "type":"viber_trans",
      "messageData":{
        "fileUrl":"https://domain.com/test.pdf",
        "fileName":"Test.pdf",
        "fileType":"pdf"
      }
    }
  ]
}

5.3. Тип повідомлення Viber Carousel

JSON

{
  "messages":[
    {
      "from":"ALPHANAME",
      "to":"380936670003",
      "type":"viber_promo",
      "text": "Text for Viber",
      "ttl": 300,
      "messageData": {
           "carousel": {
                    "items": [
                        {
                            "title": "50% Off on All Shoes!",
                            "imageUrl": "https://cdn-web.smsbat.com/help/carusel.png",
                            "primaryButton": {
                                "label": "Shop Now",
                                "actionUrl": "https://help.noetikos.org"
                            },
                            "secondaryButton": {
                                "label": "View Details",
                                "actionUrl": "https://omni.noetikos.org"
                            }
                        },
                        {
                            "title": "New Arrivals: Summer Collection",
                            "imageUrl": "https://cdn-web.smsbat.com/help/carusel.png",
                            "primaryButton": {
                                "label": "Explore",
                                "actionUrl": "https://help.noetikos.org"
                            },
                            "secondaryButton": {
                                "label": "Learn More",
                                "actionUrl": "https://omni.noetikos.org"
                            }
                        }
                    ]
                }
            }
        }
    ]
}

5.4. Тип повідомлення Viber Survey

JSON

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "type": "viber_survey",
      "text": "Тестовое сообщение",
      "ttl": 30,
      "messageData": {
        "survey": {
          "options": [
            "option1 text",
            "option2 text",
            "option3 text",
            "option4 text",
            "option5 text"
          ]
        }
      }
    }
  ]
}

5.5. Тип повідомлення Viber OTP

JSON

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "type": "viber_otp",
      "text": "",
      "ttl": "90",
      "messageData":{
        "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
        "templateLang": "uk",
        "templateParams": {
          "pin": 321,
          "business_platform_name": "SMSBAT",
          "code_validity_time": 7
        }
      }
    }
  ]
}

Шаблони OTP (1-9)

1. 1. Базовий OTP

Template ID: 0aac888f-2ee2-4112-9659-1755a951966a

English Copy:

Ваш код: Будь ласка, не діліться кодом з НІКИМ. Ми ніколи не зателефонуємо і не напишемо вам з проханням надати його.

Parameters & Validations

– TEXT

2. 2. Базовий OTP дійсний 5 хвилин

Template ID: c2cdc028-a48b-4187-bbaf-3aaa137b6e23

English Copy:

Ваш код: Він дійсний протягом 5 хвилин. Будь ласка, не діліться кодом з НІКИМ. Ми ніколи не зателефонуємо і не напишемо вам з проханням надати його.

Parameters & Validations

– TEXT

3. 3. OTP з назвою бізнесу/платформи

Template ID: c33cccaf-735f-4d62-8383-a76bf4999e2d

English Copy:

Parameters & Validations

– TEXT, – TEXT

4. 4. Базовий OTP з часом дії коду

Template ID: bed0942f-e07e-4879-834b-29cc4cf3ec35

English Copy:

Ваш код: Він дійсний протягом хвилин. Будь ласка, не діліться кодом з НІКИМ. Ми ніколи не зателефонуємо і не напишемо вам з проханням надати його.

Parameters & Validations

– TEXT, – NUMBER

5. 5. OTP з типом коду та часом дії

Template ID: 60d67b38-b9fb-444a-80e6-754447e010c6

English Copy:

Parameters & Validations

– TEXT, – TEXT, – NUMBER

6. 6. OTP з назвою бізнесу/платформи та часом дії

Template ID: 6c929cef-29b4-4349-bc9d-2a07bdbb6e43

English Copy:

Ваш код: Він дійсний протягом годин. Будь ласка, не діліться кодом з НІКИМ. Ми ніколи не зателефонуємо і не напишемо вам з проханням надати його.

Parameters & Validations

– TEXT, – TEXT, – NUMBER

7. 7. OTP з типом коду

Template ID: 82ba31a3-db42-4e87-82e8-33fa92b9e5ed

English Copy:

Parameters & Validations

– TEXT, – TEXT

8. 8. OTP з деталями дії OTP/платформи

Template ID: 210ee8a9-1ed5-43cd-96e4-65bba311ab40

English Copy:

Parameters & Validations

– TEXT, – TEXT, – TEXT

9. 9. OTP з назвою бізнесу/платформи та причиною коду

Template ID: be56d97b-2a33-4c89-ac5f-f555a2c827d9

English Copy:

Ваш код:

Parameters & Validations

– TEXT, – TEXT, – TEXT

Валідація змінних

Усі змінні є чутливими до регістру (case-sensitive) та мають точну назву, як зазначено нижче.

Variable Types

TEXT

Підтримується довільний рядок (ASCII/UTF-8). 0-довжина – не допускається.

NUMBER

Ціле число (int). 0-значення не допускається.

Regular rules

Доступний лише один тип змінної в шаблоні: або тощо. У всіх шаблонах змінні мають бути оголошені точно вказаним регістром і форматі.

Локалізація

Підтримувані мови та їх ISO-коди

ISO Language Codes

Supported Languages

EN, ES, FR, DE, PT, RU, TR, JA, ZH, KO, AR, FA, NO, DA, SV, CS, HU, NL, PL, VI

Note

Якщо потрібна інша мова, зв'яжіться з підтримкою.

5.6. Тип повідомлень RCS

RCS (Rich Communication Services) дозволяє передавати текст, зображення, відео, файли, кнопки та каруселі в одному повідомленні для нативного Android‑досвіду.

Типи відвантаження

Текст
Текст + кнопка
Картинка + текст + кнопка
Відео + (текст + кнопка) — опціонально
Файл + (текст + кнопка) — опціонально
Карусель

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

- запит

Текст

JSON

{
  "messages":[
    {
      "from":"ALPHANAME",
      "to":"380936670003",
      "type":"rcs",
      "text":"Text for RCS"
    }
  ]
}

- запит

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

JSON

{
  "messages":[
    {
      "from":"ALPHANAME",
      "to":"380936670003",
      "type":"rcs",
      "text":"Text for RCS",
      "messageData":{
        "suggestions":[
          {
            "sugText":"RCS Button",
            "sugUrl":"https://smsbat.com/"
          }
        ]
      }
    }
  ]
}

- запит

Картинка + текст + кнопка

JSON

{
  "messages":[
    {
      "from":"ALPHANAME",
      "to":"380936670003",
      "type":"rcs",
      "text":"Text for RCS",
      "messageData":{
        "img":"https://cdn-web.smsbat.com/help/carusel.png",
        "suggestions":[
          {
            "sugText":"RCS Button",
            "sugUrl":"https://smsbat.com/"
          }
        ]
      }
    }
  ]
}

- запит

Відео + (текст і кнопка) опціонально

JSON

{
  "messages":[
    {
      "from":"ALPHANAME",
      "to":"380936670003",
      "type":"rcs",
      "text":"Text for RCS",
      "messageData":{
        "video":"http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4",
        "suggestions":[
          {
            "sugText":"RCS Button",
            "sugUrl":"https://smsbat.com/"
          }
        ]
      }
    }
  ]
}

- запит

Файл + (текст і кнопка) опціонально

JSON

{
  "messages":[
    {
      "from":"ALPHANAME",
      "to":"380936670003",
      "type":"rcs",
      "text":"Text for RCS",
      "messageData":{
        "fileUrl":"https://img.freepik.com/file.docx",
        "suggestions":[
          {
            "sugText":"RCS Button",
            "sugUrl":"https://smsbat.com/"
          }
        ]
      }
    }
  ]
}

- запит

Карусель

JSON

{
  "messages":[
    {
      "from":"ALPHANAME",
      "to":"380936670003",
      "type":"rcs",
      "text":"Text for RCS",
      "messageData":{
        "rcsCarousel":[
          {
            "message":"RCS message 1",
            "rcsMedia":"https://omnicell.ua/images/Price-5.png",
            "suggestions":[
              {
                "sugText":"Button text 1",
                "sugUrl":"https://google.com.ua"
              }
            ]
          },
          {
            "message":"RCS message 2",
            "rcsMedia":"https://omnicell.ua/images/Price-5.png",
            "suggestions":[
              {
                "sugText":"Button text 2",
                "sugUrl":"https://google.com.ua"
              }
            ]
          },
          {
            "message":"RCS message 3",
            "rcsMedia":"https://omnicell.ua/images/Price-5.png",
            "suggestions":[
              {
                "sugText":"Button text 3",
                "sugUrl":"https://google.com.ua"
              }
            ]
          }
        ]
      }
    }
  ]
}

5.7. Flash Call

JSON

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

6. Вхідні Viber-повідомлення

Доступні callback-запити в сторону клієнта з передачею вхідного Viber-повідомлення, прийнятого платформою.

Поля callback

idUuid

string

ID вхідного повідомлення в нашій системі (UUID)

alphaName

string

Альфаімя, на яке написав користувач

phoneNumber

string

Номер телефону користувача

text

string

Текст повідомлення

datetime

Дата/час запиту

Як скористатися?

Надайте нам Ваш callback-URL для прив'язки в альфа-імені.

7. Fallback повідомлення

Налаштуйте fallback повідомлення коли основна доставка не вдалася

7.1. Viber Promo Fallback

SMS fallback для Viber промо повідомлень

JSON

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "type": "viber_promo",
      "text": "Text for Viber",
      "ttl": "300",
      "messageData": {
        "img": "https://cdn-web.smsbat.com/help/carusel.png",
        "buttonText": "Button text",
        "buttonAction": "https://help.smsbat.com"
      },
      "fallbacks": [
        {
          "from": "ALPHANAME",
          "to": "380936670003",
          "type": "sms",
          "text": "Замовлення №111 вже чекає на тебе в магазині",
          "ttl": "5600"
        }
      ]
    }
  ]
}

7.2. Viber Survey Fallback

SMS fallback для Viber опитувань

JSON

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "type": "viber_survey",
      "text": "Тестовое сообщение",
      "ttl": 30,
      "messageData": {
        "survey": {
          "options": [
            "option1 text",
            "option2 text",
            "option3 text",
            "option4 text",
            "option5 text"
          ]
        }
      },
      "fallbacks": [
        {
          "from": "ALPHANAME",
          "to": "380936670003",
          "text": "test sms fallback message2",
          "type": "sms"
        }
      ]
    }
  ]
}

7.3. Viber Transactional Fallback

SMS fallback для Viber транзакційних повідомлень

JSON

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "type": "viber_trans",
      "text": "Text for Viber",
      "ttl": "300",
      "messageData": {},
      "fallbacks": [
        {
          "from": "ALPHANAME",
          "to": "380936670003",
          "type": "sms",
          "text": "Text for SMS",
          "ttl": "5600"
        }
      ]
    }
  ]
}

7.4. Flash Call Каскад

Багатоканальний fallback для flash call верифікації

JSON

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "type": "flashcall",
      "text": 321,
      "ttl": "30",
      "fallbacks": [
        {
          "from": "ALPHANAME",
          "to": "380936670003",
          "type": "viber_otp",
          "text": "",
          "ttl": "90",
          "messageData": {
            "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
            "templateLang": "uk",
            "templateParams": {
              "pin": 321,
              "business_platform_name": "SMSBAT",
              "code_validity_time": 7
            }
          }
        },
        {
          "from": "ALPHANAME",
          "to": "380936670003",
          "type": "sms",
          "text": "Text for SMS 321"
        }
      ]
    }
  ]
}

SMSBAT RESTful API

Огляд

1. Протокол

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

Логін та пароль (HTTP Basic Authentication)

API-ключ в заголовку

API-ключ як пароль

3. Надсилання повідомлень

Одиночне повідомлення

Масове повідомлення

Відповідь API

4. Статус повідомлень

4.1. Відповідь статусу

4.2. Приклад Fallback відповіді

5. Особливості типів повідомлень

5.1. Тип повідомлення Viber Promo

Тільки картинка

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

Тільки текст

Картинка + текст + кнопка

Відео + текст

Відео + текст + кнопка

Тільки відео

5.2. Тип повідомлення Viber Transactional

Тільки текст

PDF файл + текст

Тільки PDF файл

5.3. Тип повідомлення Viber Carousel

5.4. Тип повідомлення Viber Survey

5.5. Тип повідомлення Viber OTP

Шаблони OTP (1-9)

1. 1. Базовий OTP

2. 2. Базовий OTP дійсний 5 хвилин

3. 3. OTP з назвою бізнесу/платформи

4. 4. Базовий OTP з часом дії коду

5. 5. OTP з типом коду та часом дії

6. 6. OTP з назвою бізнесу/платформи та часом дії

7. 7. OTP з типом коду

8. 8. OTP з деталями дії OTP/платформи

9. 9. OTP з назвою бізнесу/платформи та причиною коду

Валідація змінних

Локалізація

5.6. Тип повідомлень RCS

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

Текст

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

Картинка + текст + кнопка

Відео + (текст і кнопка) опціонально

Файл + (текст і кнопка) опціонально

Карусель

5.7. Flash Call

6. Вхідні Viber-повідомлення

7. Fallback повідомлення

7.1. Viber Promo Fallback

7.2. Viber Survey Fallback

7.3. Viber Transactional Fallback

7.4. Flash Call Каскад