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

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

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

Ендпоінт

GET /bat/message/{messageId}

Запит

Параметри URL

ПараметрТипОбов’язковоОпис
messageIdstringТакУнікальний ідентифікатор повідомлення (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
}

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

ПолеТипОпис
messagelistIdintegerІдентифікатор партії (розсилки)
messageIdstringУнікальний ідентифікатор конкретного повідомлення
deliverystatusstringПоточний статус доставки
partscountintegerКількість SMS-сегментів (частин), на які розбито повідомлення
costnumberВартість повідомлення у відповідній валюті

Розширена Відповідь (Із 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) з інтервалом в декілька мілісекунд, щоб не сповільнювати власні системи та не навантажувати наші.

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