Статусы сообщений

Коротко: статусы показывают, что произошло с отправленным сообщением: доставлено, прочитано, была ошибка. Есть два способа их получать — push (мы отправляем) и pull (вы запрашиваете сами).

Кому подходит

• Роль: Разработчик, Интегратор
• Уровень: Опытный

Что это

После отправки сообщения важно знать его дальнейшую судьбу:

• Дошло ли оно до получателя.
• Прочитал ли он его.
• Была ли ошибка и какая.
• Сколько стоила отправка.

Эти данные и есть статусы. Они помогают обновлять состояние в своей CRM, уведомлять менеджера, считать стоимость, запускать резервный канал.

Два способа получения статусов

Можно использовать один способ или оба одновременно.

Push — платформа отправляет статусы

Платформа сама отправляет статус на ваш URL по мере изменения состояния сообщения: отправлено, доставлено, прочитано.

Что нужно с вашей стороны

1. Поднять эндпоинт, который принимает POST-запросы и отвечает кодом 200 OK. Например: https://ваш-сайт.com/webhook/iba.
2. Указать этот URL одним из способов:
   • в поле webhook в каждом запросе;
   • в настройках имени отправителя;
   • в настройках API-ключа.
3. Обрабатывать входящие статусы на своей стороне.

Пример: запрос от платформы на ваш вебхук

{
  "event": "messageStatus",
  "message": {
    "messageId": "4aab1947-7a34-4efe-8c51-e9c8f9b1412b",
    "omniTransactionId": "57f29fdd-1127-45b3-a7d5-260a831a4662",
    "channel": 1,
    "senderId": "sender_name",
    "status": "delivered",
    "timestamp": "2023-09-08T15:30:00Z",
    "contact": "905324546496",
    "cost": "1.00"
  }
}

Возможные статусы

Статус рассылки

Pull — запрашиваете статусы сами

Вы обращаетесь к API и запрашиваете статусы по нужным фильтрам. Это удобно, когда статусы нужны не сразу, а например, при сверке раз в час или раз в день.

Эндпоинт: GET /api/v1/edrs

Параметры запроса

Пример 1. Запрос по ID сообщений

curl --location 'https://web.multiapi.ru/api/v1/edrs?messageIds=6719b5f4-36af-4fba-b111-49ff07f4f96b,75bb9087-fc19-4940-a004-c2723337cb2f' \
  --header 'X-API-Key: <ваш-ключ>'

Пример 2. Запрос за период

curl --location 'https://web.multiapi.ru/api/v1/edrs?timeFrom=2024-01-01T00:00:00Z&timeTo=2024-01-02T00:00:00Z&limit=50' \
  --header 'X-API-Key: <ваш-ключ>'

Пример 3. Запрос по номеру телефона

curl --location 'https://web.multiapi.ru/api/v1/edrs?phoneNumbers=905324546496&limit=20' \
  --header 'X-API-Key: <ваш-ключ>'

Формат ответа

{
  "count": 2,
  "limit": 100,
  "offset": 0,
  "data": [
    {
      "messageId": "6719b5f4-36af-4fba-b111-49ff07f4f96b",
      "channelType": 1,
      "senderId": "sender_name",
      "isSent": true,
      "isDelivered": true,
      "isSeen": false,
      "mdnStatus": "DELIVRD",
      "timeSent": "2024-01-01T10:00:00Z",
      "timeDelivered": "2024-01-01T10:00:05Z",
      "timeSeen": null,
      "finalCost": 0.0248,
      "country": "RU",
      "network": "MTS",
      "errorMessage": null
    }
  ]
}

Поля ответа

Что можно делать со статусами

• Обновлять состояние сообщения в своей CRM.
• Уведомлять менеджера о недоставке.
• Считать стоимость отправки.
• Запускать резервный канал (например, если сообщение не доставлено по WhatsApp — отправить через SMS).

Частые проблемы

См. также

Нужна помощь?

• Multi API: support@multiapi.ru