Перейти до змісту

Перевірка Статусу Повідомлення

Відстежуйте статуси доставки ваших повідомлень (відправлено, доставлено, помилка) в режимі реального часу за допомогою ендпоінту перевірки статусу.

Ендпоінт

GET /bat/message/{messageId}

Запит

Параметри URL

Параметр Тип Обов'язково Опис
messageId string Так Унікальний ідентифікатор повідомлення (messageId), отриманий в результаті запиту на відправку

Авторизація

Використовуйте будь-який з наших трьох методів:

# Приклад (API Key Header)
curl -X GET https://restapi.smsbat.com/bat/message/abc123def456 \
  -H "X-Authorization-Key: ваш-api-ключ"

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

Стандартна Відповідь

{
  "messagelistId": 123456,
  "messageId": "abc123def456",
  "deliverystatus": "delivered",
  "partscount": 1,
  "cost": 0.05
}

Поля Відповіді

Поле Тип Опис
messagelistId integer Ідентифікатор партії (розсилки)
messageId string Унікальний ідентифікатор конкретного повідомлення
deliverystatus string Поточний статус доставки
partscount integer Кількість SMS-сегментів (частин), на які розбито повідомлення
cost number Вартість повідомлення у відповідній валюті

Розширена Відповідь (Із Fallback)

Коли ви використовуєте каскадну розсилку (наприклад, Viber → SMS), відповідь включатиме додаткові відомості:

{
  "messagelistId": 123456,
  "messageId": "abc123def456",
  "deliverystatus": "delivered",
  "partscount": 1,
  "cost": 0.05,
  "fallbacks": [
    {
      "type": "sms",
      "status": "not_used"
    }
  ],
  "extendedStatuses": {
    "viber": "delivered",
    "sms": "not_used"
  },
  "rate": 0.05,
  "rateAmount": 0.05,
  "rateCurrency": "USD",
  "billAmount": 0.05,
  "billCurrency": "USD"
}

Життєвий Цикл Статусів (Delivery Status Values)

graph LR
    A[scheduled] --> B[processing]
    B --> C[delivered]
    B --> D[undeliverable]
    B --> E[permanenterror]

Ось таблиця очікуваних значень поля deliverystatus:

Статус Опис
scheduled Прийнято в чергу системи (Очікує відправки)
processing Наразі опрацьовується або передається оператору
delivered Успішно доставлено на кінцевий пристрій клієнта
undeliverable Сталася помилка (недоступний номер, помилка оператора чи відмова)
permanenterror Видалено з черги через критичну помилку (напр. неправильний формат номера)

1. В Черзі (Scheduled)

Запит прийнятий системою та чекає своєї черги: 

{
  "deliverystatus": "scheduled",
  "partscount": 1
}

2. В Процесі (Processing)

Система передала інформацію до провайдера чи мобільного оператора, очікується квитанція про кінцеву доставку: 

{
  "deliverystatus": "processing",
  "partscount": 1
}

3. Доставлено (Delivered)

Оператор з впевненістю підтвердив доставку повідомлення до абонента: 

{
  "deliverystatus": "delivered",
  "partscount": 1,
  "cost": 0.05
}

4. Недоставлено (Undeliverable / Error)

{
  "deliverystatus": "undeliverable",
  "partscount": 1,
  "cost": 0.00
}
Можлива причина: абонент знаходиться поза межами покриття мережі більше ніж тривалість вашого TTL.

Polling проти Webhook'ів

Polling (Періодичні запити)

Ви можете періодично надсилати запит на статус (напр. кожні 5 секунд). Ми настійно не рекомендуємо спамити ендпоінт "частіше ніж 1 раз на секунду" задля уникнення блокування доступу через Rate Limiting (перевищення ліміту навантаження). Радимо використовувати стратегію Exponential Backoff.

Альтернатива: Вебхуки (Webhooks)

Замість того, щоб кожну секунду питати в системи статус, значно краще налаштувати отримання вебхуків. Так SMSBAT сам повідомить ваш сервер, коли статус повідомлення зміниться:

POST https://ваш-сервер.com/smsbat-webhook

{
  "messageId": "abc123def456",
  "deliverystatus": "delivered",
  "timestamp": "2025-01-23T10:30:00Z",
  "cost": 0.05
}

Примітка: щоб підключити вебхуки та вказати свій URL-приймач (Callback URL), зверніться до вашого особистого менеджера.

Оптимізація запитів

Якщо ви хочете перевіряти статус одразу кількох повідомлень водночас, вам варто робити об'ємні запити пачками (batched requests) з інтервалом в декілька мілісекунд, щоб не сповільнювати власні системи та не навантажувати наші.

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