Help Center Cascade API

Cascade API

The Cascade API delivers one message through several channels with a single request: Telegram bot, Viber bot, Viber Business Messages, RCS, SMS, email and push. You define the order; the platform tries the channels one after another and reports the channel that actually delivered.

Base URL

https://restapi.smsbat.com

OpenAPI / Swagger

The full, machine-readable specification is public:

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

The request schema is LegacyMessageDataDTO; the SMS/other fallback element is LegacyFallbackDTO; the Viber part is LegacyViberMessage; the Telegram part is LegacyTelegramMessageData.

Authentication

Requests are authenticated with headers:

Header	Purpose
`X-Authorization-Key`	Organization API key for Cascade. Generated in omni.smsbat.com. This is not the same key as the one used for `https://api.smsbat.com/bat/messagelist`.
`X-Viber-Auth-Token`	Token of the Viber bot the message is sent through. Required for Viber bot delivery, because an organization can have several bots.
`X-Tg-Bot-Key`	Token of the Telegram bot the message is sent through. Required for Telegram bot delivery.

curl -X POST https://restapi.smsbat.com/api/CascadeMessage/send_message_async \
  -H "Content-Type: application/json" \
  -H "X-Authorization-Key: <organization key from omni.smsbat.com>" \
  -H "X-Viber-Auth-Token: <viber bot token>" \
  -d @request.json

Bot tokens are stored in your organization in the SMSBAT panel, but they still have to be sent with every request so the platform knows which bot to use.

Endpoints

Method	Endpoint	Description
POST	`/api/CascadeMessage/send_message_async`	Accepts the batch and returns immediately; delivery statuses arrive via callbacks. Recommended.
POST	`/api/CascadeMessage/send_message`	Synchronous variant of the same request.
POST	`/api/CascadeMessage/send_message/omni-smsbat/tg-viber/async`	Cascade with Telegram → Viber priority.
GET	`/api/CascadeMessage/status_guid/{guid}`	Status of a message by the SMSBAT `messageId`.
GET	`/api/CascadeMessage/status_id/{id}`	Status of a message by your own `id`.

How it works

Telegram bot → Viber bot → Viber Business → RCS → SMS

One request, an array of messages. For every message the platform tries the channels you configured; when a channel cannot deliver (the user is not in the bot, the number has no Viber, the message expired), the next fallback is used. The callback tells you which channel finally delivered.

Two rules to keep in mind:

Without toPhone the message goes to the bot only. Viber Business and SMS need a phone number: either toPhone on the message or toPhone in the corresponding fallbacks[] element.
Bot recipients are identified by their bot ids: tgMessage.chatId for Telegram and viberMessage.receiver for Viber. This is required when the bot runs on your side and its users are not synced to SMSBAT.

Request in one look

[
  {
    "id": "ORDER-12345",
    "callbackUrl": "https://example.com/smsbat/status",
    "fromName": "YourBrand",
    "toPhone": "380501234567",
    "messageType": "transaction",
    "ttl": 60,
    "viberMessage": {
      "type": "text",
      "sender": { "name": "YourBrand" },
      "text": "Your order #12345 has been shipped",
      "fallbacks": [
        {
          "messageType": "sms",
          "toPhone": "380501234567",
          "fromName": "YourBrand",
          "ttl": 60,
          "text": "Your order #12345 has been shipped"
        }
      ]
    }
  }
]

Phone numbers: international format, digits only, without + (380501234567).

Every field is described on the Send Cascade Messages page.

Response

200 OK with one object per message, in the same order as the request:

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

messageId — SMSBAT message GUID; the same value comes back in callbacks as message_id.
trackinId — your id from the request; comes back in callbacks as track_id.

400 Bad Request — the whole batch is rejected, the reason is in the response body; nothing from that request is sent, so the corrected batch can be resubmitted without duplicates.

Delivery statuses

Statuses are delivered to the callbackUrl of each message (or to the organization-level callback URL) as POST requests with a JSON body, one object per event. Format, statuses and retry rules: Delivery Callbacks. The same information can be polled with the status_guid / status_id endpoints.

Limits

Request body: up to 10 MB.
No validation of the number of messages in one array; the body size is the only limit.
No per-second or per-minute request limits for the Cascade API. Group messages into batches instead of sending one request per message.

Message types and variables

Message Types — transaction, promo, viber_survey, flashcall.
Message Variables — %name=id%, %url=id%, %short_url=id%.

Testing

For integration we set up a sandbox: a separate organization in omni.smsbat.com with test bots and keys. Callbacks can be pointed at any HTTPS endpoint you control; on request our team sends test status events to your endpoint by hand. Ask your account manager or help@smsbat.com.

Search Results