Сумісність з TurboSMS API

SMSBAT повністю підтримує шар сумісності з API TurboSMS. Це дозволяє вам мігрувати існуючі інтеграції, які були розроблені для TurboSMS, безпосередньо до SMSBAT без необхідності переписувати структури повідомлень або тіла запитів до ендпоінтів.

Ми підтримуємо відправку SMS та Viber повідомлень (включаючи розширені функції, такі як каруселі та опитування), отримання статусів доставки та деталей повідомлень за допомогою тієї ж структури запитів, до якої ви вже звикли.

Аутентифікація

Єдина відмінність від оригінального API TurboSMS полягає в механізмі аутентифікації. У той час як TurboSMS використовує кастомний параметр token або специфічний заголовок, SMSBAT вимагає стандартний Bearer Token.

Ви повинні передавати ваш API-токен SMSBAT у заголовку Authorization для всіх запитів:

Authorization: Bearer YOUR_SMSBAT_TOKEN

Базовий URL

Усі запити повинні бути направлені до базового URL API SMSBAT:

https://restapi.smsbat.com

---

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

Ендпоінт: POST /api/tsms/message/send

Дозволяє відправляти SMS та Viber повідомлення з підтримкою гібридної доставки (Viber з резервним SMS). Обробляє один запит на відправку та повертає результати доставки для кожного одержувача.

Ключові можливості

• Гнучкі параметри: Глобальні параметри можуть бути перевизначені специфічними параметрами для SMS/Viber.
• Контент: Підтримує Viber-каруселі, опитування, вкладення файлів та інтерактивні кнопки.
• Обробка помилок: Повертає HTTP 200 навіть для помилок (структуровані відповіді з помилками). response_code: 999 зі статусом FATAL_ERROR для системних помилок.
• Помилки одержувачів: Специфічні помилки одержувачів повертаються в масиві response_result. Неуспішні одержувачі мають message_id: null та специфічні коди помилок.

Приклад запиту (Гібридне повідомлення)

{
  "sender": "GlobalSender",
  "text": "Тестове повідомлення",
  "recipients": ["380951111111", "380952222222"],
  "start_time": "2025-09-29T10:00:00Z",
  "sequence_id": "seq_12345",
  "sms": {
    "sender": "SMSSender",
    "text": "SMS версія повідомлення",
    "is_flash": false
  },
  "viber": {
    "sender": "ViberSender",
    "text": "Viber версія повідомлення",
    "ttl": 3600,
    "image_url": "https://example.com/image.png",
    "caption": "Текст кнопки",
    "action": "https://google.com",
    "count_clicks": true,
    "is_transactional": false
  }
}

Приклад запиту (Viber Карусель)

{
  "sender": "GlobalSender",
  "text": "Перегляньте наші товари",
  "recipients": ["380951111111"],
  "viber": {
    "sender": "ViberSender",
    "text": "Перегляньте наші товари",
    "is_transactional": false,
    "carousel": [
      {
        "title": "Товар 1",
        "image_url": "https://example.com/product1.jpg",
        "button_caption": "Купити",
        "button_url": "https://example.com/buy/product1",
        "link_caption": "Детальніше",
        "link_url": "https://example.com/product1"
      },
      {
        "title": "Товар 2",
        "image_url": "https://example.com/product2.jpg",
        "button_caption": "Купити",
        "button_url": "https://example.com/buy/product2",
        "link_caption": "Детальніше",
        "link_url": "https://example.com/product2"
      }
    ]
  }
}

Приклад запиту (Viber Опитування)

{
  "sender": "GlobalSender",
  "text": "Оцініть наш сервіс",
  "recipients": ["380951111111"],
  "viber": {
    "sender": "ViberSender",
    "text": "Оцініть наш сервіс",
    "is_transactional": true,
    "survey": [
      "Відмінно",
      "Добре",
      "Задовільно",
      "Погано"
    ]
  }
}

---

Пакетна відправка повідомлень

Ендпоінт: POST /api/tsms/message/sendmulti

Цей метод дозволяє надсилати декілька запитів send в одному HTTP-запиті, економлячи час на встановлення з’єднання. Виклик sendmulti з даними для 100 запитів буде набагато швидшим, ніж виконання 100 окремих send запитів.

Приклад запиту

{
  "batch_1": {
    "sender": "GlobalSender",
    "text": "Тестове повідомлення",
    "recipients": ["380982462128", "380501111111"],    
    "sms": {
        "sender": "SMSSender",
        "text": "SMS версія повідомлення"
    }
  },
  "batch_2": {
    "sender": "GlobalSender",
    "text": "Друге повідомлення",
    "recipients": ["380501111111"],
    "viber": {
      "sender": "ViberSender",
      "text": "Viber повідомлення",
      "is_transactional": true
    }
  }
}

Приклад відповіді

{
    "response_code": 0,
    "response_status": "OK",
    "response_result": {
        "batch_1": {
            "response_code": 800,
            "response_status": "SUCCESS_MESSAGE_ACCEPTED",
            "response_result": [
                {
                    "phone": "380982462128",
                    "response_code": 0,
                    "message_id": "f1640579-ea75-4bc1-b708-1c3858bf222d",
                    "response_status": "OK"
                }
            ]
        },
        "batch_2": { ... }
    }
}

---

Отримання статусу повідомлення

Ендпоінт: POST /api/tsms/message/status

Дозволяє отримати статуси доставки відправлених повідомлень за допомогою їх message_id.

Приклад запиту

{
  "messages": [
      "573dcb46-7851-4e16-bb1f-721c13ef5f38", 
      "6b7f9ff5-28c8-4f38-913b-31af6021fbea"
  ]
}

---

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

Ендпоінт: POST /api/tsms/message/details

Дозволяє отримати детальну інформацію про створені повідомлення, включаючи повні дані про канали SMS та Viber, вартість, і точні мітки часу.

Приклад запиту

{
  "messages": [
      "573dcb46-7851-4e16-bb1f-721c13ef5f38", 
      "f1640579-ea75-4bc1-b708-1c3858bf222d"
  ]
}

Приклад відповіді

{
    "response_code": 0,
    "response_status": "OK",
    "response_result": [
        {
            "message_id": "573dcb46-7851-4e16-bb1f-721c13ef5f38",
            "sms": null,
            "viber": {
                "added": "2025-09-29T14:17:02.577Z",
                "start": "2025-09-29T10:00:00Z",
                "sent": "2025-09-29T14:17:02.577Z",
                "updated": "2025-09-29T14:17:02.577Z",
                "sender": "ViberSender",
                "text": "Viber версія повідомлення",
                "recipient": "380982462128",
                "message_type": "promotional",
                "status": "Queued",
                "price": 0,
                "ttl": 3600,
                "caption": "Текст кнопки",
                "action": "https://google.com"
            },
            "response_code": 0,
            "response_status": "OK"
        }
    ]
}