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

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

Надсилайте повідомлення через безліч каналів одним-єдиним запитом до API. Cascade автоматично маршрутизує ваше повідомлення через Telegram Bot, Viber Bot, Business Viber, RCS та SMS.

Ендпоінти

Стандартний Каскад

POST /api/CascadeMessage/send_message/async

Маршрутизує повідомлення через усі доступні та вказані канали по черзі.

Пріоритет Telegram-Viber

POST /api/CascadeMessage/send_message/tg-viber/async

Надає найвищий пріоритет ботам Telegram та Viber для найшвидшої доставки.

Авторизація

Cascade API приймає три типи заголовків авторизації. У запиті має бути щонайменше один з них:

ЗаголовокОпис
X-Authorization-KeySMSBAT API ключ (рекомендовано)
X-Viber-Auth-TokenТокен Viber бота
X-Tg-Bot-KeyТокен Telegram бота

Структура Запиту

Заголовки (Headers)

Content-Type: application/json
X-Authorization-Key: ваш-smsbat-api-ключ
X-Viber-Auth-Token: ваш-viber-token
X-Tg-Bot-Key: ваш-telegram-key

Тіло (Body)

API приймає масив із об’єктами повідомлень:

[
  {
    "id": "unic-id-for-tracking",
    "fromName": "YourBrand",
    "toPhone": "+380XXXXXXXXX",
    "messageType": "transaction",
    "text": "Ваше замовлення #12345 підтверджено",
    "ttl": 3600,
    "scheduledSent": "2025-01-25T10:00:00Z"
  }
]

Параметри

ПараметрТипОбов’язковоОпис
idstringТакВаш зовнішній трекінг ідентифікатор
fromNamestringТакІм’я відправника (Альфа-ім’я)
toPhonestringТакТелефон отримувача у форматі E.164
messageTypestringТакТип повідомлення: transaction, promo, viber_survey, flashcall
textstringТак*Основний текст контенту (*обов’язково для більшості типів)
ttlintegerНіЧас життя (Time-to-live) у секундах
scheduledSentstringНіISO 8601 дата та час відкладеної відправки

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

Transaction (Транзакційні)

Важливі сповіщення, такі як підтвердження замовлень чи зміни акаунту:

{
  "id": "order-12345",
  "fromName": "YourStore",
  "toPhone": "+380XXXXXXXXX",
  "messageType": "transaction",
  "text": "Ваше замовлення #12345 укомплектовано і прибуде завтра.",
  "ttl": 86400
}

Promo (Промоційні)

Маркетингові кампанії з графікою або інтерактивними елементами:

{
  "id": "promo-summer-sale",
  "fromName": "YourBrand",
  "toPhone": "+380XXXXXXXXX",
  "messageType": "promo",
  "text": "Літній Сейл! Знижки до -50%. Відвідайте: https://example.com/sale",
  "ttl": 259200
}

Viber Survey (Опитування)

Інтерактивні голосування з 2-5 опціями відповіді:

{
  "id": "survey-satisfaction",
  "fromName": "YourBrand",
  "toPhone": "+380XXXXXXXXX",
  "messageType": "viber_survey",
  "text": "Наскільки ви задоволені нашим обслуговуванням?",
  "surveyOptions": [
    "Дуже задоволений",
    "Задоволений",
    "Нейтрально",
    "Не задоволений",
    "Вкрай не задоволений"
  ],
  "ttl": 604800
}

Максимальна довжина тексту питання: 85 символів.

Flash Call (Флеш кол)

Телефонна аутентифікація шляхом короткого автоматичного дзвінка (код у номері або просто розпізнавання номера):

{
  "id": "verify-user-123",
  "fromName": "YourApp",
  "toPhone": "+380XXXXXXXXX",
  "messageType": "flashcall",
  "ttl": 300
}

Приклади

Стандартна транзакція

curl -X POST https://restapi.smsbat.com/api/CascadeMessage/send_message/async \
  -H "Content-Type: application/json" \
  -H "X-Authorization-Key: your-api-key" \
  -d '[
    {
      "id": "tx-001",
      "fromName": "YourBank",
      "toPhone": "+380XXXXXXXXX",
      "messageType": "transaction",
      "text": "Платіж на суму 2000 грн виконано успішно. ID: ABC123"
    }
  ]'

Відкладене Промо

curl -X POST https://restapi.smsbat.com/api/CascadeMessage/send_message/async \
  -H "Content-Type: application/json" \
  -H "X-Authorization-Key: your-api-key" \
  -d '[
    {
      "id": "promo-001",
      "fromName": "YourStore",
      "toPhone": "+380XXXXXXXXX",
      "messageType": "promo",
      "text": "Чорна п'ятниця через годину! Завітай: https://example.com",
      "scheduledSent": "2025-01-25T09:00:00Z",
      "ttl": 3600
    }
  ]'

Масове відправлення (Bulk)

curl -X POST https://restapi.smsbat.com/api/CascadeMessage/send_message/async \
  -H "Content-Type: application/json" \
  -H "X-Authorization-Key: your-api-key" \
  -d '[
    {
      "id": "bulk-001",
      "fromName": "YourBrand",
      "toPhone": "+380111111111",
      "messageType": "transaction",
      "text": "Повідомлення 1"
    },
    {
      "id": "bulk-002",
      "fromName": "YourBrand",
      "toPhone": "+380222222222",
      "messageType": "transaction",
      "text": "Повідомлення 2"
    },
    {
      "id": "bulk-003",
      "fromName": "YourBrand",
      "toPhone": "+380333333333",
      "messageType": "transaction",
      "text": "Повідомлення 3"
    }
  ]'

Відповідь (Response)

Успішна Відповідь

[
  {
    "messageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "trackinId": "tx-001"
  },
  {
    "messageId": "8b2f1e9a-4c6d-4e2a-9f8b-1a3d5c7e9f0b",
    "trackinId": "tx-002"
  }
]

Значення Полів Відповіді

ПолеТипОпис
messageIdstring (UUID)Внутрішній ідентифікатор повідомлення в системі
trackinIdstringВаш трекінг ідентифікатор (переданий у запиті)

Використовуйте messageId для перевірки статусу (webhook/status API), а trackinId – для логічної кореляції з вашою бекенд-системою.

Best Practices (Кращі Практики)

Номери телефонів

Завжди передавайте номери у форматі E.164:

  • ✅ +380XXXXXXXXX
  • ❌ 380XXXXXXXXX
  • ❌ 0XXXXXXXXX

Трекінгові ID (id / trackinId)

  • Контролюйте унікальність кожного ID.
  • Додавайте інформаційний префікс (наприклад order-12345, promo-summer-2025).
  • Максимальна довжина – 255 символів.
  • Уникайте пробілів та спецсимволів.

Час життя (TTL)

Рекомендовані значення TTL в залежності від типу повідомлення:

  • Підтвердження та OTP: 300-600 секунд (5-10 хвилин)
  • Транзакційні: 3600-86400 секунд (1-24 години)
  • Промоційні (Маркетинг): 86400-259200 секунд (1-3 дні)
  • Опитування (Survey): 604800 секунд (7 днів)

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

  • Завжди надсилайте час у часовому поясі UTC (Z в кінці, ISO8601).
  • Не відкладайте доставку більше ніж на 30 днів.

Масові запити (Bulk Batching)

  • Надсилайте пакети по 100-1000 повідомлень в одному JSON масиві.
  • Реалізуйте власні ліміти та бекофи на випадок 429 Too Many Requests.
  • Зберігайте обробку помилок на вашій стороні.

Обробка помилок (Error Handling)

HTTP Статуси

КодОпис
200Успішно створено та поставлено в чергу (Success)
400Некоректний запит (Bad request) – помилкові параметри чи формат
401Не авторизовано (Unauthorized) – ключ неправильний чи застарілий
429Забагато запитів (Too many requests) – перевищено ліміт платформи
500Внутрішня помилка сервера (Server error)

Структура Помилки в тілі відповіді

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Invalid phone number format",
    "field": "toPhone"
  }
}

Наступні кроки