---
title: Вебхуки
description: Вебхуки IBA Platform — статусы сообщений, входящие сообщения, статусы рассылок. Разрешение URL, форматы, статусы
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://docs.mydialogi.ru/llms.txt). Append `.md` to any page URL for its markdown version.



> **Коротко:** вебхук — это URL, на который платформа отправляет события: статусы сообщений, входящие сообщения и статусы рассылок. URL задаётся в трёх местах, платформа использует первый непустой.

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

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

## Что такое вебхук

Вебхук — это HTTP-запрос, который платформа отправляет на указанный вами URL, когда происходит событие. Так вы получаете уведомления о статусах сообщений, ответах получателей и статусах рассылок.

## Как задаётся URL вебхука

Вебхук разрешается в следующем порядке (используется первое непустое значение):

1. Поле `webhook` в теле запроса.
2. Вебхук, настроенный для имени отправителя.
3. Вебхук, настроенный для API-доступа (API-ключ или Basic Auth).

Если ни одно значение не задано, вебхук не отправляется.

## Типы событий

| Событие | Когда приходит | Источник |
|---|---|---|
| `messageStatus` | Изменился статус сообщения | OMNI API |
| `message` | Получено входящее сообщение (MO) | OMNI API |
| Статус рассылки | Изменился статус рассылки | Broadcasts API |

## Статус сообщения (`messageStatus`)

Отправляется в эндпоинтах OMNI API, когда сообщение меняет статус.

**Формат:**

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

**Поля:**

| Поле | Тип | Что означает |
|---|---|---|
| event | string | Тип события: `messageStatus` |
| message.messageId | string | Уникальный идентификатор сообщения |
| message.omniTransactionId | string | ID каскадного запроса (может быть пустым) |
| message.channel | integer | Номер канала |
| message.senderId | string | Имя отправителя |
| message.status | string | Статус сообщения (см. таблицу ниже) |
| message.timestamp | string | Время события (RFC3339) |
| message.contact | string | Номер получателя |
| message.cost | float | Стоимость сообщения (может быть пустой) |
| message.clientInfo | string | Произвольное поле из запроса (может быть пустым) |
| reason | object | Причина ошибки (если есть) |

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

| Статус | Что означает |
|---|---|
| sent | Сообщение отправлено |
| delivered | Сообщение доставлено |
| displayed | Сообщение прочитано |
| failed | Ошибка отправки |
| undeliverable | Сообщение не доставлено |
| unknown | Неизвестный или неподдерживаемый статус |

**Причина ошибки (`reason`):**

| Поле | Тип | Что означает |
|---|---|---|
| code | integer | Код ошибки |
| text | string | Описание ошибки |

### Альтернатива: pull-запрос

Вебхук — это **push-способ**: платформа сама отправляет статус на ваш URL.

Если push не подходит — например, удобно обойтись без своего эндпоинта или статусы нужны пачкой раз в час — статусы можно **запрашивать самостоятельно** через API. Это **pull-способ**.

Эндпоинт: `GET /api/v1/edrs` — возвращает записи о доставке сообщений.

Подробнее о двух способах получения статусов — в статьях по сервисам:

- [Статусы сообщений в OTP-кодах](https://docs.mydialogi.ru/02-otp/08-api/otp-api-statuses)
- [Статусы сообщений в Multi API](https://docs.mydialogi.ru/03-multiapi/02-api/mapi-106-api-statuses)
- [Статусы сообщений в «Мой диалог»](https://docs.mydialogi.ru/04-mydialogi/09-api/md-api-statuses)

## Входящее сообщение (`message`)

Отправляется, когда получатель отвечает на ваше сообщение (MO — Mobile Originated).

**Формат:**

```json
{
  "event": "message",
  "message": {
    "messageId": "4aab1947-7a34-4efe-8c51-e9c8f9b1412b",
    "omniTransactionId": "57f29fdd-1127-45b3-a7d5-260a831a4662",
    "timestamp": "2023-09-08T15:30:00Z",
    "channel": "SMS",
    "senderId": "2813380676",
    "contact": "8172958708",
    "payload": {
      "text": "test SMS"
    }
  }
}
```

**Поля:**

| Поле | Тип | Что означает |
|---|---|---|
| event | string | Тип события: `message` |
| message.messageId | string | Уникальный идентификатор |
| message.omniTransactionId | string | ID каскадного запроса |
| message.timestamp | string | Время события (RFC3339) |
| message.channel | string | Канал: `SMS`, `RCS`, `Viber`, `WhatsApp`, `UNSET` |
| message.senderId | string | Имя отправителя |
| message.contact | string | Номер отправителя |
| message.payload | object | Содержимое сообщения (зависит от канала) |

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

Отправляется из Broadcasts API. Приходит, когда рассылка меняет статус.

**Формат:**

| Поле | Тип | Что означает |
|---|---|---|
| status | string | Обновлённый статус рассылки |
| webhook | string | URL вебхука |
| broadcastId | integer | ID рассылки |
| message | string | Описание ошибки (если есть) |

## См. также

<Columns cols={2}>
  <Card title="Обработка ошибок API" icon="triangle-exclamation" href="/06-reference/01-api/api-errors">
    HTTP-коды и форматы ответов
  </Card>
  <Card title="Обзор API" icon="book" href="/06-reference/01-api/api-overview">
    Единое API платформы
  </Card>
  <Card title="Swagger UI" icon="code" href="/06-reference/01-api/api-swagger">
    Ссылки на интерактивную документацию
  </Card>
  <Card title="API-ключи" icon="key" href="/06-reference/01-api/api-keys">
    Создание и управление ключами
  </Card>
</Columns>

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

- OTP-коды: support@otpcod.ru
- Multi API: support@multiapi.ru
- Мой диалог: support@mydialogi.ru