---
title: Статусы сообщений
description: Как получать статусы отправленных сообщений Multi API — через push (вебхук) или pull (запрос к API)
---
> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.
# Статусы сообщений
> **Коротко:** статусы показывают, что произошло с отправленным сообщением: доставлено, прочитано, была ошибка. Есть два способа их получать — push (мы отправляем) и pull (вы запрашиваете сами).
## Кому подходит
- Роль: Разработчик, Интегратор
- Уровень: Опытный
## Что это
После отправки сообщения важно знать его дальнейшую судьбу:
- Дошло ли оно до получателя.
- Прочитал ли он его.
- Была ли ошибка и какая.
- Сколько стоила отправка.
Эти данные и есть **статусы**. Они помогают обновлять состояние в своей CRM, уведомлять менеджера, считать стоимость, запускать резервный канал.
## Два способа получения статусов
| Способ | Кто инициирует | Когда использовать |
|---|---|---|
| **Push** | Платформа отправляет статусы вам | Когда нужны статусы в реальном времени |
| **Pull** | Вы запрашиваете статусы сами | Когда нужны статусы пачкой — например, при сверке отчётов |
Можно использовать один способ или оба одновременно.
## Push — платформа отправляет статусы
Платформа сама отправляет статус на ваш URL по мере изменения состояния сообщения: отправлено, доставлено, прочитано.
### Что нужно с вашей стороны
1. Поднять эндпоинт, который принимает POST-запросы и отвечает кодом `200 OK`. Например: `https://ваш-сайт.com/webhook/iba`.
2. Указать этот URL одним из способов:
- в поле `webhook` в каждом запросе;
- в настройках имени отправителя;
- в настройках API-ключа.
3. Обрабатывать входящие статусы на своей стороне.
### Пример: запрос от платформы на ваш вебхук
```json
{
"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"
}
}
```
### Возможные статусы
| Статус | Что означает |
|---|---|
| sent | Сообщение отправлено |
| delivered | Сообщение доставлено |
| displayed | Сообщение прочитано |
| failed | Ошибка отправки |
| undeliverable | Сообщение не доставлено |
| unknown | Неизвестный статус |
Если от провайдера приходит ошибка (недоступен абонент, неверный номер и т. п.), статус придёт как `failed` или `undeliverable`. В поле `reason` будет описание ошибки.
### Статус рассылки
Статус **рассылки** (не отдельного сообщения) приходит только через push — на вебхук, указанный при запуске рассылки в поле `webhook`. Pull-эндпоинта для статуса рассылки нет.
Формат вебхука статуса рассылки описан в статье [Broadcasts API](/03-multiapi/02-api/mapi-105-broadcasts-api).
## Pull — запрашиваете статусы сами
Вы обращаетесь к API и запрашиваете статусы по нужным фильтрам. Это удобно, когда статусы нужны не сразу, а например, при сверке раз в час или раз в день.
**Эндпоинт:** `GET /api/v1/edrs`
### Параметры запроса
| Параметр | Тип | Что указать |
|---|---|---|
| messageIds | string | Список ID сообщений через запятую (1–10 штук) |
| timeFrom | string | Начало периода (например, `2024-01-01T00:00:00Z`) |
| timeTo | string | Конец периода. Указывается обязательно вместе с `timeFrom` |
| phoneNumbers | string | Список номеров телефонов через запятую (1–10 штук) |
| broadcastRunId | integer | ID запуска рассылки |
| offset | integer | Смещение |
| limit | integer | Максимум записей. По умолчанию 100 |
Указывайте либо `messageIds`, либо `timeFrom` + `timeTo`. Остальные параметры — опциональны.
### Пример 1. Запрос по ID сообщений
```bash
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. Запрос за период
```bash
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. Запрос по номеру телефона
```bash
curl --location 'https://web.multiapi.ru/api/v1/edrs?phoneNumbers=905324546496&limit=20' \
--header 'X-API-Key: <ваш-ключ>'
```
### Формат ответа
```json
{
"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
}
]
}
```
### Поля ответа
| Поле | Что означает |
|---|---|
| messageId | ID сообщения |
| channelType | Номер канала |
| senderId | Имя отправителя |
| isSent | Отправлено |
| isDelivered | Доставлено |
| isSeen | Прочитано |
| mdnStatus | Статус от оператора |
| timeSent | Время отправки |
| timeDelivered | Время доставки |
| timeSeen | Время прочтения |
| finalCost | Итоговая стоимость |
| country / network | Страна и оператор |
| errorMessage | Ошибка (если есть) |
## Что можно делать со статусами
- Обновлять состояние сообщения в своей CRM.
- Уведомлять менеджера о недоставке.
- Считать стоимость отправки.
- Запускать резервный канал (например, если сообщение не доставлено по WhatsApp — отправить через SMS).
## Частые проблемы
**Причина:** ваш эндпоинт не отвечает кодом `200 OK` или недоступен.
**Решение:** проверьте, что URL открыт из интернета и возвращает `200 OK`. Платформа повторяет отправку при ошибке.
**Причина:** стоимость может быть не рассчитана на момент отправки статуса.
**Решение:** запросите статус повторно через `GET /edrs` — там поле `finalCost` заполняется.
**Причина:** по указанным фильтрам нет сообщений, или период указан неверно.
**Решение:** проверьте `messageIds`, период или номер телефона. Если запрашиваете по периоду — оба поля `timeFrom` и `timeTo` обязательны.
**Причина:** неверный или отсутствующий API-ключ.
**Решение:** проверьте заголовок `X-API-Key`. Подробнее: [Ошибка 401](/06-reference/03-troubleshooting/ts-mapi-401).
## См. также
Аутентификация и базовый URL
Отправка сообщений, каскад, шаблоны
Запуск рассылок, шаблоны
Все типы вебхуков платформы
## Нужна помощь?
- Multi API: support@multiapi.ru