Към съдържанието

Ръководство за RESTful API на SMSBAT

Пълно ръководство за RESTful API на SMSBAT – всичко, което трябва да знаете.

Последно обновяване: 29 Август, 2025

RESTful API на SMSBAT ви позволява да изпращате различни типове съобщения: Viber карусел (carousel), Viber анкета (survey), Viber промо (изображения, видео), бизнес чатове на Viber, OTP съобщения (Viber OTP, Flash Call) и техните резервни (fallback) варианти.

Забележка: Това е унифицираният HTTP API за изходящи съобщения. Ако се нуждаете от интеграции с входящи ботове (Viber Bot / Telegram Bot), моля, вижте документацията за Cascade API.

1. Протокол

  • Протокол: HTTPS
  • Тяло на заявката (Request Body): JSON обект, съдържащ масив от съобщения (messages).
  • Методи:
  • GET за извличане на данни (статус на съобщението, баланс и др.)
  • POST за създаване на обекти (напр. иницииране на изпращане)
  • PATCH за промяна на обекти

2. Авторизация (Authorization)

Предоставяме няколко метода за оторизация за ваше удобство: - HTTP базова автентикация (Basic Authentication) - потребителско име (login) и парола от вашето табло за управление. - Персонализирана (Custom) HTTP заглавка (Header) X-Authorization-Key, съдържаща API токен. - Поле за парола за HTTP Basic Authentication, което съдържа API токена (предоставете @ като потребителско име / login).

API Токенът може да бъде генериран в таблото за управление в Потребителски профил (User Profile).

Примери за заявки

С базов Auth (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).

Крайна точка (Endpoint) - Метод: POST - URL: https://api.smsbat.com/bat/messagelist - Заглавки (Headers): Content-Type: application/json

Основна структура (Payload): 

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "text": "Вижте нашите нови продукти!",
      "type": "viber_carousel",
      "ttl": 300,
      "messageData": { ... }
    }
  ]
}

Задължителни полета за всеки обект (message)

  • from: Потвърдено алма-име (alpha-name) на подателя.
  • to: Телефонен номер на получателя (формат E.164).
  • type: Тип съобщение (enum).
  • text: Основен текст на съобщението (по избор, ако типът не изисква текст).

Поддържани стойности за type: - sms - viber_service (или viber_trans) - viber_promo - viber_carousel - viber_survey - viber_otp - viber_session - flashcall_callback - flashcall

Незадължителни (опционални) общи полета:

  • customerMessageId: Стрингов идентификатор във вашата собствена система (използва се за проследяване на callbacks). Трябва да бъде уникален за всяко съобщение.
  • dtSend: ISO8601 дата/час на планирано изпращане в бъдещето.
  • dtExpire: ISO8601 дата/час на краен срок за доставка.
  • ttl: Време за живот (Time-To-Live) в секунди. (Ако dtExpire не е предоставено, API-то изчислява стойностите по подразбиране спрямо type).

TTL по подразбиране (в секунди):

  • sms - 86400 (24 часа)
  • viber_trans / viber_service - 345600
  • viber_promo - 604800
  • viber_session - 604800

4. Резервен маршрут (Fallback Routing / Cascading)

Можете да посочите резервна (fallback) опашка, за да осигурите доставката на съобщението, ако основният канал се провали (fail) или изтече.

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380500505051",
      "text": "тестово съобщение",
      "type": "viber_service",
      "ttl": 60,
      "fallbacks": [
        {
          "from": "ALPHANAME",
          "to": "380936670003",
          "text": "тест резервно sms съобщение2",
          "type": "sms"
        }
      ]
    }
  ]
}
Функцията "fallback" се задейства, когато доставчикът (provider) откаже главното съобщение или когато изтече TTL.

5. Преглед на видовете съобщения и messageData

Сложните (complex) типове съобщения изискват допълнителни конфигурации, които трябва да се вмъкнат (напишат) в свойството messageData.

5.1 Viber Promo (viber_promo)

Само изображение (Image Only) 

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

Текст + Бутон (Text + Button) 

"messageData":{
  "buttonText":"Запази сега",
  "buttonAction":"https://help.smsbat.com"
}

Изображение + Текст + Бутон Комбинира img, buttonText и buttonAction.

Видео полезен товар (Video Payload): 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(Можете също да комбинирате видео свойствата с buttonText и buttonAction).

5.2 Транзакционен / Услуга Viber (viber_trans, viber_service)

Ако имате одобрен шаблон, който съдържа прикачен файл: 

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

Изисква масив (array) carousel.items в messageData.

Ограничения (Limitations): - Дължина на елементите: между 2 и 5 елемента - Заглавие (Title): от 2 до 38 знака - imageUrl: JPEG/PNG препоръчителен размер 215x185

"messageData": {
  "carousel": {
    "items": [
      {
        "title": "50% Отстъпка на обувки!",
        "imageUrl": "https://domain.com/image1.png",
        "primaryButton": { "label": "Пазарувай", "actionUrl": "..." },
        "secondaryButton": { "label": "Подробности", "actionUrl": "..." }
      }
    ]
  }
}

5.4 Анкета (Survey) на Viber / Списък (viber_survey)

Създава интерактивна анкета в рамките на чата (chat view). 

"messageData": {
  "survey": {
    "options": [
      "Отлично", "Добре", "Нормално", "Лошо", "Ужасно"
    ]
  }
}
Свойството (property) text на съобщението действа като заглавие на анкетата (Максимум 85 знака). Можете да предадете (зададете) между 2 и 5 опции (всяка макс. 50 символа).

5.5 Viber OTP (viber_otp)

Използва предварително регистрирани локализирани Viber шаблони в световен мащаб. 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "bg",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
Параметрите на шаблона (pin, business_platform_name) са строго чувствителни към малки и главни букви (case-sensitive). API-то поддържа различни опции ISO за език (EN, ES, RU, TR, UK, BG и др.).

5.6 Flash Call (Тихо обаждане) (flashcall)

Последните цифри от набиращия се номер (генерираният код) трябва да се подадат чрез параметъра text. Ако text е пропуснат, кодът се рандомизира (променя произволно) и трябва да го извлечете от синхронното 200 OK Response body на API (messages/text).

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