Центр допомоги Надсилання каскаду

Надсилання каскаду

Надсилайте пакет повідомлень через Telegram-бот, Viber-бот, Viber Business Messages, RCS і SMS одним запитом. Точна схема опублікована у Swagger-специфікації (LegacyMessageDataDTO).

Ендпоінт

POST https://restapi.smsbat.com/api/CascadeMessage/send_message_async

send_message_async приймає пакет і одразу відповідає; статуси доставки надходять через callback. Є також синхронний POST /api/CascadeMessage/send_message, а POST /api/CascadeMessage/send_message/omni-smsbat/tg-viber/async запускає каскад із пріоритетом Telegram → Viber.

Заголовки

Content-Type: application/json
X-Authorization-Key: <ключ організації з omni.smsbat.com>
X-Viber-Auth-Token: <токен viber-бота>      # коли повідомлення йде через Viber-бот
X-Tg-Bot-Key: <токен telegram-бота>         # коли повідомлення йде через Telegram-бот

Ключ організації для Cascade генерується в omni.smsbat.com і відрізняється від ключа для /bat/messagelist. Токени ботів ідентифікують бота: в організації їх може бути кілька, тому токен обов’язковий для доставки в бот.

Тіло запиту

Тіло — JSON-масив об’єктів повідомлень.

Об’єкт повідомлення

Поле	Тип	Опис
`id`	string	Ваш ідентифікатор для відстеження. Повертається як `trackinId` у відповіді і як `track_id` у callback.
`callbackUrl`	string	HTTPS-URL, на який приходять статуси доставки цього повідомлення. Query-рядок зберігається як є.
`fromName`	string	Ім’я відправника (альфа-ім’я) для Viber Business / SMS.
`toPhone`	string	Телефон одержувача: міжнародний формат, лише цифри, без `+` (`380501234567`). Необов’язковий: без нього повідомлення доставляється лише в бот, Viber Business / SMS не використовуються.
`messageType`	string	`transaction`, `promo`, `viber_survey`, `flashcall`. Див. Типи повідомлень.
`ttl`	integer	Час життя в секундах. Після його закінчення повідомлення отримує статус `expired`.
`viberMessage`	object	Viber-частина повідомлення, див. нижче.
`tgMessage`	object	Telegram-частина повідомлення, див. нижче.
`emailMessage`, `pushMessage`	object	Email- і push-частини, див. Swagger.
`customerData`	any	Ваші власні дані, що зберігаються з повідомленням.
`flashcallText`, `buttonText`, `buttonAction`	string	Текст flash call і кнопка для каналів, які її підтримують.

`viberMessage`

Поле	Тип	Опис
`receiver`	string	Ідентифікатор користувача Viber-бота. Використовуйте, коли бот працює на вашому боці і ви самі зберігаєте ідентифікатори.
`type`	string	`text`, `picture`, `video`, `file`, `contact`, `location`, `sticker`.
`sender.name`, `sender.avatar`	string	Відправник, який відображається в боті.
`text`	string	Текст повідомлення, до 7000 символів.
`media`, `thumbnail`, `video`, `fileName`, `size`, `duration`		Атрибути медіа для нетекстових типів.
`keyboard`	object	Клавіатура Viber.
`trackingData`	string	Tracking data Viber.
`fallbackText`	string	Текст для фолбек-каналів, якщо в них немає власного тексту.
`fallbacks`	array	Фолбек-канали в порядку спроб, див. нижче.

`tgMessage`

Поле	Тип	Опис
`chatId`	integer (int64)	Telegram chat id одержувача у вашому боті.
`text`	string	Текст повідомлення.
`photoUrl`, `photoBase64`, `videoUrl`	string	Медіа.
`buttons`	масив `{ "text", "action" }`	Inline-кнопки.

`fallbacks[]`

Кожен елемент описує наступний канал для спроби. Поля, задані тут, перевизначають значення рівня повідомлення для цього каналу.

Поле	Тип	Опис
`messageType`	string	Канал/тип фолбеку, наприклад `sms`.
`toPhone`	string	Телефон для цього фолбеку (лише цифри, без `+`). Може відрізнятися від `toPhone` повідомлення.
`fromName`	string	Ім’я відправника для цього фолбеку.
`ttl`	integer	TTL цього фолбеку в секундах.
`text`	string	Текст для цього фолбеку.
`media`, `thumbnail`, `video`, `fileName`, `size`, `duration`, `contact`, `location`, `buttonText`, `buttonAction`		Необов’язкові атрибути для медіа-фолбеків.

Приклад: Viber-бот з SMS-фолбеком і callback-адресою

curl --request POST \
  --url https://restapi.smsbat.com/api/CascadeMessage/send_message_async \
  --header 'Content-Type: application/json' \
  --header 'X-Authorization-Key: 61192c5***' \
  --header 'X-Viber-Auth-Token: 5646dd4***' \
  --data '[
  {
    "callbackUrl": "https://example.com/smsbat/status?channel=viber-bot",
    "id": "DEVELOPER-TEST-SDFLW122",
    "fromName": "YourBrand",
    "toPhone": "380509180617",
    "messageType": "transaction",
    "ttl": 60,
    "viberMessage": {
      "type": "text",
      "sender": { "name": "YourBrand" },
      "text": "Це текст для Viber",
      "fallbacks": [
        {
          "messageType": "sms",
          "toPhone": "380509180617",
          "fromName": "YourBrand",
          "ttl": 60,
          "text": "SMS-текст для YourBrand"
        }
      ]
    }
  }
]'

Приклад: лише в бот, одержувач за ідентифікатором бота

Без toPhone повідомлення доставляється лише в бот; додайте viberMessage.receiver (Viber) або tgMessage.chatId (Telegram).

[
  {
    "id": "ORDER-12345",
    "callbackUrl": "https://example.com/smsbat/status?channel=telegram-bot",
    "messageType": "transaction",
    "ttl": 3600,
    "tgMessage": {
      "chatId": 123456789,
      "text": "Ваше замовлення #12345 відправлено"
    }
  }
]

Відповідь

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

[
  { "messageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "trackinId": "DEVELOPER-TEST-SDFLW122" }
]

Поле	Опис
`messageId`	GUID повідомлення в SMSBAT. Приходить як `message_id` у callback; використовуйте з `GET /api/CascadeMessage/status_guid/{guid}`.
`trackinId`	Ваш `id`. Приходить як `track_id` у callback; використовуйте з `GET /api/CascadeMessage/status_id/{id}`.

400 Bad Request — пакет відхиляється цілком, причина в тілі відповіді. Якщо один елемент невалідний, жоден елемент не надсилається, тому виправлений пакет можна надіслати повторно без дублювання. Інші коди: 401 (невірний ключ), 5xx (наш бік, повторіть пізніше).

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

Відповідь лише підтверджує прийняття. Події доставки, прочитання, закінчення TTL і помилок надсилаються на callbackUrl повідомлення (або на адресу рівня організації, якщо в повідомленні її немає). Формат і статуси: Статуси доставки (callback). Опитування: GET /api/CascadeMessage/status_guid/{guid} або GET /api/CascadeMessage/status_id/{id}.

Обмеження

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

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