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

Изпращайте съобщения през различни канали с една единствена 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"
  }
}

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

• Променливи в съобщенията - Използвайте динамично съдържание
• Видове съобщения - Разгледайте типовете съобщения
• Състояние на доставка - Проследете доставките си