Центр допомоги Cascade API

Cascade API

Cascade API доставляє одне повідомлення через кілька каналів одним запитом: Telegram-бот, Viber-бот, Viber Business Messages, RCS, SMS, email і push. Ви задаєте порядок, платформа пробує канали по черзі й повідомляє, який канал фактично доставив.

Базовий URL

https://restapi.smsbat.com

OpenAPI / Swagger

Повна машиночитана специфікація публічна:

Swagger UI: https://restapi.smsbat.com/swagger/index.html
OpenAPI 3.0 JSON: https://restapi.smsbat.com/swagger/v1/swagger.json

Схема запиту — LegacyMessageDataDTO; елемент SMS/іншого фолбеку — LegacyFallbackDTO; Viber-частина — LegacyViberMessage; Telegram-частина — LegacyTelegramMessageData.

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

Запити автентифікуються заголовками:

Заголовок	Призначення
`X-Authorization-Key`	Ключ організації для Cascade. Генерується в omni.smsbat.com. Це не той самий ключ, що використовується для `https://api.smsbat.com/bat/messagelist`.
`X-Viber-Auth-Token`	Токен Viber-бота, через який надсилається повідомлення. Обов’язковий для доставки у Viber-бот, бо в організації може бути кілька ботів.
`X-Tg-Bot-Key`	Токен Telegram-бота, через який надсилається повідомлення. Обов’язковий для доставки в Telegram-бот.

curl -X POST https://restapi.smsbat.com/api/CascadeMessage/send_message_async \
  -H "Content-Type: application/json" \
  -H "X-Authorization-Key: <ключ організації з omni.smsbat.com>" \
  -H "X-Viber-Auth-Token: <токен viber-бота>" \
  -d @request.json

Токени ботів зберігаються у вашій організації в панелі SMSBAT, але їх усе одно потрібно передавати з кожним запитом, щоб платформа знала, який бот використати.

Ендпоінти

Метод	Ендпоінт	Опис
POST	`/api/CascadeMessage/send_message_async`	Приймає пакет і одразу відповідає; статуси доставки приходять через callback. Рекомендований.
POST	`/api/CascadeMessage/send_message`	Синхронний варіант того самого запиту.
POST	`/api/CascadeMessage/send_message/omni-smsbat/tg-viber/async`	Каскад із пріоритетом Telegram → Viber.
GET	`/api/CascadeMessage/status_guid/{guid}`	Статус повідомлення за `messageId` SMSBAT.
GET	`/api/CascadeMessage/status_id/{id}`	Статус повідомлення за вашим `id`.

Як це працює

Telegram-бот → Viber-бот → Viber Business → RCS → SMS

Один запит, масив повідомлень. Для кожного повідомлення платформа пробує налаштовані канали; коли канал не може доставити (користувача немає в боті, на номері немає Viber, повідомлення прострочене), береться наступний фолбек. Callback повідомляє, який канал зрештою доставив.

Два правила, які варто пам’ятати:

Без toPhone повідомлення йде лише в бот. Для Viber Business і SMS потрібен номер телефону: або toPhone у повідомленні, або toPhone у відповідному елементі fallbacks[].
Одержувачі в боті ідентифікуються ідентифікаторами бота: tgMessage.chatId для Telegram і viberMessage.receiver для Viber. Це обов’язково, коли бот працює на вашому боці і його користувачі не синхронізовані зі SMSBAT.

Запит одним поглядом

[
  {
    "id": "ORDER-12345",
    "callbackUrl": "https://example.com/smsbat/status",
    "fromName": "YourBrand",
    "toPhone": "380501234567",
    "messageType": "transaction",
    "ttl": 60,
    "viberMessage": {
      "type": "text",
      "sender": { "name": "YourBrand" },
      "text": "Ваше замовлення #12345 відправлено",
      "fallbacks": [
        {
          "messageType": "sms",
          "toPhone": "380501234567",
          "fromName": "YourBrand",
          "ttl": 60,
          "text": "Ваше замовлення #12345 відправлено"
        }
      ]
    }
  }
]

Номери телефонів: міжнародний формат, лише цифри, без + (380501234567).

Усі поля описані на сторінці Надсилання каскаду.

Відповідь

200 OK з одним об’єктом на кожне повідомлення, у тому ж порядку, що й у запиті:

[
  {
    "messageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "trackinId": "ORDER-12345"
  }
]

messageId — GUID повідомлення в SMSBAT; те саме значення приходить у callback як message_id.
trackinId — ваш id із запиту; приходить у callback як track_id.

400 Bad Request — відхиляється весь пакет, причина в тілі відповіді; нічого з цього запиту не надсилається, тому виправлений пакет можна надіслати повторно без дублювання.

Статуси доставки

Статуси надходять на callbackUrl кожного повідомлення (або на callback-URL рівня організації) як POST-запити з JSON, один об’єкт на подію. Формат, статуси та правила повторів: Статуси доставки (callback). Ту саму інформацію можна опитувати через ендпоінти status_guid / status_id.

Обмеження

Тіло запиту: до 10 МБ.
Кількість повідомлень в одному масиві не валідується; єдине обмеження — розмір тіла.
Лімітів запитів за секунду чи хвилину для Cascade API немає. Групуйте повідомлення в пакети замість одного запиту на повідомлення.

Типи повідомлень і змінні

Типи повідомлень — transaction, promo, viber_survey, flashcall.
Змінні повідомлень — %name=id%, %url=id%, %short_url=id%.

Тестування

Для інтеграції ми створюємо sandbox: окрему організацію в omni.smsbat.com з тестовими ботами та ключами. Callback можна спрямувати на будь-який ваш HTTPS-ендпоінт; за запитом наша команда надішле тестові статуси на ваш ендпоінт вручну. Зверніться до менеджера або на help@smsbat.com.

Результати пошуку