Центр допомоги Статуси доставки (callback)

Статуси доставки (callback)

Cascade API асинхронний: запит на надсилання лише підтверджує, що пакет прийнято. Події доставки, прочитання, закінчення TTL і помилок надсилаються на ваш сервер як HTTP-callback. Статуси також можна опитувати.

Куди надсилаються callback

На рівні повідомлення: поле callbackUrl повідомлення в запиті на надсилання. Query-рядок зберігається і надсилається як є, тому https://example.com/status?channel=viber-bot приходить із незмінним query.
На рівні організації: одна callback-адреса для всієї організації, яка використовується, коли в повідомленні немає callbackUrl. Може містити ваш заголовок авторизації (headerName / headerValue). Керується через GET/POST/PUT/DELETE /organizations/callback_urls (див. Swagger) або через вашого менеджера.

Адреса callback не залежить від каналу, який зрештою доставив повідомлення: усі події одного повідомлення йдуть на його єдину адресу, а канал доставки вказаний у полі channel. Якщо вашому приймачу потрібні окремі ендпоінти для різних ботів, передавайте різні значення callbackUrl у повідомленнях, які надсилаєте через кожен бот.

Формат запиту

POST на callback-URL із Content-Type: application/json. Один JSON-об’єкт на подію; події не групуються в пакети.

{
  "message_id": "c7a1b2d3-1111-2222-3333-444455556666",
  "track_id": "ORDER-12345",
  "channel": "viber",
  "status": "delivered",
  "delivered_at": "2026-08-21T14:29:00Z",
  "read_at": null,
  "timestamp": "2026-08-21T14:30:00Z"
}

Поле	Опис
`message_id`	GUID повідомлення в SMSBAT, тобто `messageId` з відповіді на надсилання.
`track_id`	Ваш `id` із запиту на надсилання; `null`, якщо не передавався.
`channel`	Канал, який фактично доставив повідомлення, див. нижче. `null`, якщо канал не визначено.
`status`	Поточний/фінальний статус, див. нижче.
`delivered_at`	Час доставки (UTC, ISO 8601).
`read_at`	Час прочитання; заповнюється лише для Viber-каналів.
`timestamp`	Час формування callback.

Поле з причиною для undeliverable / blocked наразі не повертається.

Канали

`channel`	Значення
`telegram`	Доставлено через Telegram-бота
`viber_bot`	Доставлено через Viber-бота
`viber`	Доставлено через Viber Business Messages
`sms`	Доставлено через SMS, у тому числі SMS-фолбек
`email`	Доставлено через email
`push`	Доставлено через push (Firebase)
`null`	Канал не визначено

Статуси

`status`	Значення
`delivered`	Доставлено на пристрій
`read`	Прочитано одержувачем (лише Viber і Viber-бот)
`undeliverable`	Доставити неможливо: номер недоступний, провайдер відхилив або всі канали каскаду не спрацювали
`expired`	TTL повідомлення минув до доставки
`canceled`	Відмінено
`blocked`	Контакт у промо-стоп-листі або не пройшов валідацію; нічого не надіслано

Доставка та повтори

Відповідайте HTTP 200, щоб підтвердити отримання callback.
Якщо ваш сервер не відповів, callback повторюється 3 рази.
Callback надсилаються на кожну подію, тому одне повідомлення може дати кілька (наприклад, delivered, потім read).

Опитування замість callback

GET /api/CascadeMessage/status_guid/{guid}   # за messageId SMSBAT
GET /api/CascadeMessage/status_id/{id}       # за вашим id

Використовуйте ті самі заголовки автентифікації, що й для надсилання.