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

Изпращане на каскадни съобщения

Изпращайте съобщения през различни канали с една единствена API заявка. Cascade автоматично маршрутизира (насочва) вашето съобщение през Telegram Bot, Viber Bot, Viber Business Messages, RCS и SMS.

Крайни точки (Endpoints)

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

POST /api/CascadeMessage/send_message/async

Насочва съобщенията през всички налични канали в последователност.

Приоритет на Telegram-Viber

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

Приоритизира Telegram и Viber каналите за по-бърза доставка.

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

Cascade API поддържа три заглавки (хедъра) за удостоверяване. Включете поне един:

Хедър Описание
X-Authorization-Key SMSBAT API ключ (препоръчително)
X-Viber-Auth-Token Данни за вашия Viber бот
X-Tg-Bot-Key Ключ за вашия Telegram бот

Структура на заявката

Заглавки

Content-Type: application/json
X-Authorization-Key: your-smsbat-api-key
X-Viber-Auth-Token: your-viber-token
X-Tg-Bot-Key: your-telegram-key

Тяло на заявката (Body)

Изпратете масив (array) от обекти за съобщения:

[
  {
    "id": "unique-tracking-id",
    "fromName": "YourBrand",
    "toPhone": "+380XXXXXXXXX",
    "messageType": "transaction",
    "text": "Вашата поръчка #12345 е потвърдена",
    "ttl": 3600,
    "scheduledSent": "2025-01-25T10:00:00Z"
  }
]

Параметри

Параметър Тип Задължителен Описание
id string Да Вашият идентификатор за проследяване
fromName string Да Име на подателя (Alpha Name)
toPhone string Да Телефонен номер на получателя (формат E.164)
messageType string Да Тип на съобщението: transaction, promo, viber_survey, flashcall
text string Да* Съдържание на съобщението (* задължително за повечето типове)
ttl integer Не Време на живот (Time-to-live) в секунди
scheduledSent string Не ISO 8601 дата и час за планирана доставка

Примери

Основна транзакция

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": "Плащането на $100 беше успешно. 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": "Флаш разпродажбата започва след 1 час! Посетете: https://example.com",
      "scheduledSent": "2025-01-25T09:00:00Z",
      "ttl": 3600
    }
  ]'

Масово изпращане

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"
    }
  ]'

Отговор

Успешен отговор

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

Полета в отговора

Поле Тип Описание
messageId string (UUID) Системен идентификатор на съобщението
trackinId string Вашият идентификатор на проследяване (от заявката)

Използвайте messageId за проследяване на състоянието и trackinId за корелация с вашата система.

Добри практики

Телефонни номера

Винаги използвайте E.164 формат: - ✅ +380XXXXXXXXX - ❌ 380XXXXXXXXX - ❌ 0XXXXXXXXX

Идентификатори за проследяване (Tracking IDs)

  • Използвайте уникални идентификатори за всяко съобщение
  • Включете контекст в ID (напр. order-12345, promo-summer-2025)
  • Поддържайте ID под 255 знака
  • Избягвайте специални символи

TTL (Time-to-Live)

Препоръчителни стойности за TTL:

  • OTP/Верификация: 300-600 секунди (5-10 минути)
  • Транзакционни: 3600-86400 секунди (1-24 часа)
  • Промоционални: 86400-259200 секунди (1-3 дни)
  • Анкети: 604800 секунди (7 дни)

Планирани съобщения

  • Използвайте часова зона UTC за scheduledSent
  • Не планирайте повече от 30 дни предварително
  • Вземете предвид разликите в часовите зони
  • Първо тествайте с графици за близко бъдеще

Масово изпращане

  • Изпращайте на партиди от 100-1000 съобщения
  • Внедрете ограничаване на заявките (rate limiting), за да не превишите квотата
  • Обработвайте грешки грациозно
  • Опитайте отново с неуспешни съобщения чрез Exponential Backoff

Обработка на грешки

HTTP кодове за състояние

Код Описание
200 Успех
400 Лоша заявка - невалидни параметри
401 Неупълномощен достъп - невалиден API ключ
429 Твърде много заявки
500 Грешка в сървъра

Отговор за грешка

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Невалиден формат на телефонен номер",
    "field": "toPhone"
  }
}

Следващи стъпки