---
title: OMNI API — отправка сообщений
description: OMNI API Мой диалог — отправка одиночных сообщений и каскадов, параметры запроса, таблица каналов, отправка шаблонов
---
> **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.
> **Коротко:** OMNI API — единый интерфейс для отправки сообщений. Поддерживает одиночную отправку и каскадную отправку с автоматическим переключением между каналами.
## Кому подходит
- Роль: Разработчик, Интегратор
- Уровень: Опытный
## Эндпоинты
| Метод | Эндпоинт | Для чего |
|---|---|---|
| POST | `/messages` | Отправка одного сообщения |
| POST | `/omnimessages` | Каскадная отправка |
Полный URL: `https://web.mydialogi.ru/api/v1/messages` и `https://web.mydialogi.ru/api/v1/omnimessages`.
**OMNI API отправляет одно сообщение одному получателю за запрос.** Массив `messages` в эндпоинте `/omnimessages` — это **каналы каскада** для одного и того же получателя (`contact`), а не список получателей.
Для **массовой отправки** по списку номеров или фильтрам используйте [Broadcasts API](https://docs.mydialogi.ru/04-mydialogi/09-api/md-api-broadcasts) — эндпоинт `POST /broadcast/broadcasts`.
## Параметры запроса
| Поле | Тип | Обязательно | Что указать |
|---|---|---|---|
| contact | string | Да | Номер получателя с кодом страны, без «+» |
| channel | integer | Да | Номер канала (см. таблицу ниже) |
| senderId | string | Да | Имя отправителя из «Активы → Имена отправителей» |
| payload | object | Да* | Содержимое сообщения. Формат зависит от канала |
| template | object | Да* | Содержимое шаблона: `id` и `params` |
| webhook | string | Нет | URL для приёма статусов. Подробнее — [Вебхуки](https://iba-platform.jamdesk.app/06-reference/01-api/api-webhooks) |
| clientInfo | string | Нет | Произвольное поле, сохраняется в EDR |
| isOtp | boolean | Нет | Если `true` — содержимое скрывается в EDR как OTP |
| successOn | string | Нет | Только для каскада. Статус успеха: `sent`, `delivered`, `seen`. По умолчанию `sent` |
| timeout | integer | Нет | Только для каскада. Секунды до перехода на следующий канал. По умолчанию 1200 (20 минут). Максимум 259200 (3 дня) |
| cooldown | integer | Нет | Только для каскада. Секунды блокировки контакта при неудаче. По умолчанию выключено. Максимум 86400 (1 день) |
| sendNextAfterFail | boolean | Нет | Только для каскада. Отправлять ли следующее сообщение при получении статуса `failed` после наступления `successOn`. По умолчанию `false` |
| ttl | integer | Нет | Время жизни сообщения |
> *- нужен либо `payload`, либо `template`.
**Параметры на уровне сообщения.** Каждое сообщение в массиве `messages` может содержать свои поля `clientInfo`, `cooldown` и `ttl` — они переопределяют значения верхнего уровня для конкретного шага каскада.
`isOtp: true` указывайте, только если сообщение содержит одноразовый код (OTP, 2FA, код верификации). Для обычных сообщений — не указывайте.
**Как это работает:**
- Получателю уходит настоящее сообщение с кодом, например: `Ваш код подтверждения: 1234`.
- В EDR это же сообщение сохраняется с заменой кода на маску: `Ваш код подтверждения: ******`.
Так код остаётся доступен получателю, но не хранится в открытом виде в записях платформы.
## Таблица каналов
| Номер | Канал | Доступно через API |
|---|---|---|
| 1 | SMS | ✅ |
| 2 | RCS | ✅ |
| 3 | Viber | ✅ |
| 4 | WhatsApp | ✅ |
| 5 | VK/OK | ✅ |
| 6 | WeChat | ✅ |
| 7 | Email | ✅ |
| 8 | Telegram Gateway | ✅ |
| 9 | Telegram | ✅ |
| 10 | Push | ✅ |
| 11 | TTS | ✅ |
| 12 | Voice | ❌ |
| 13 | Mobile Push | ✅ |
| 14 | FlashCall | ✅ |
Не все каналы доступны для каждой компании. Полный список доступных каналов можно получить через эндпоинт `GET /channels`.
Не все каналы отправляются через OMNI API:
- **Канал 5 (VK/OK)** — отправка через API поддерживается, но информацию по настройке и параметрам нужно запросить в поддержке сервиса.
- **Канал 12 (Voice)** — через OMNI API не отправляется. Доступен только в интерфейсе платформы.
## Отправка одного сообщения
**Пример SMS:**
```bash
curl --location 'https://web.mydialogi.ru/api/v1/messages' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <ваш-ключ>' \
--data-raw '{
"contact": "905063565285",
"channel": 1,
"senderId": "",
"payload": {
"text": "Тестовое сообщение"
}
}'
```
Ответ придёт кодом `202 Accepted` с `messageId`. Факт доставки — асинхронно через вебхук.
Форматы `payload` для каждого канала смотрите в статье [Форматы payload по каналам](https://iba-platform.jamdesk.app/04-mydialogi/09-api/md-api-omni-payload) — они одинаковые для всех сервисов.
## Каскадная отправка
Запрос `POST /omnimessages` принимает массив `messages` — по объекту на каждый канал.
Для каждого сообщения (кроме последнего) можно указать:
- **`successOn`** — статус, при котором сообщение считается успешным. Если он не наступит — платформа перейдёт к следующему сообщению.
- **`timeout`** — секунды ожидания `successOn`. По умолчанию 1200 (20 минут).
**Пример: RCS → SMS с двумя шаблонами**
```bash
curl --location 'https://web.mydialogi.ru/api/v1/omnimessages' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <ваш-ключ>' \
--data-raw '{
"contact": "",
"webhook": "",
"isOtp": true,
"cooldown": 86400,
"messages": [
{
"channel": 2,
"senderId": "",
"successOn": "delivered",
"timeout": 60,
"template": {
"id": ,
"params": {
"attribute.phoneNumber": "112332",
"attribute.name": "test-name"
}
}
},
{
"channel": 1,
"senderId": "",
"template": {
"id": ,
"params": {
"attribute.phoneNumber": "112332",
"attribute.code": "1234"
}
}
}
]
}'
```
SMS отправится, если RCS **не получит статус `delivered` в течение 60 секунд** **или** если от провайдера сразу придёт статус `failed` / `undeliverable`.
У каждого канала в каскаде может быть свой шаблон или произвольный текст через `payload`.
## Отправка шаблонов
Для отправки по шаблону используйте параметр `template` вместо `payload`.
| Поле | Тип | Обязательно | Что указать |
|---|---|---|---|
| `id` | integer | Да | ID шаблона из раздела «Активы» → «Шаблоны сообщений» |
| `params` | object | Да | Атрибуты шаблона. Если шаблон без переменных — пустой объект `{}` |
**Пример:**
```bash
curl --location 'https://web.mydialogi.ru/api/v1/messages' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <ваш-ключ>' \
--data-raw '{
"contact": "",
"webhook": "",
"channel": 2,
"senderId": "",
"template": {
"id": ,
"params": {
"attribute.phoneNumber": "112332",
"attribute.name": "test-name"
}
}
}'
```
## Коды ответов
| Код | Что означает |
|---|---|
| 202 Accepted | Запрос принят |
| 400 | Ошибка параметров |
| 401 | Неверный или отсутствующий API-ключ |
| 404 | Ресурс не найден |
| 500 | Внутренняя ошибка сервера |
**Пример успешного ответа:**
```json
{
"error": false,
"data": {
"channel": 4,
"transactionId": "95e3e0da-9684-4ba4-88a3-e9207ddeca05",
"messageId": "6719b5f4-36af-4fba-b111-49ff07f4f96b"
}
}
```
## Частые проблемы
### Ошибка «Template not found»
**Причина:** неверный ID шаблона.
**Решение:** откройте раздел **Активы** → **Шаблоны сообщений**, скопируйте точный ID.
### Ошибка параметров
**Причина:** неверный ключ атрибута в `template.params`.
**Решение:** проверьте формат — например, `attribute.name`.
### 401 Unauthorized
**Причина:** неверный или отсутствующий API-ключ.
**Решение:** проверьте заголовок `X-API-Key`.
### 400 Bad Request: sender not found
**Причина:** в запросе указано имя отправителя, которое не привязано к этому ключу.
**Решение:** откройте ключ в разделе **API Подключения** и добавьте нужное имя отправителя.
### Каскад не переключается на следующий канал
**Причина:** статус, указанный в `successOn`, уже наступил — например, `sent`, а вы ждали `delivered`.
**Решение:** явно укажите `successOn: "delivered"` для каждого сообщения каскада.
## См. также
JSON-примеры для каждого канала
Запуск рассылок, шаблоны
Контакты, атрибуты, фильтры
HTTP-коды и форматы ответов
## Нужна помощь?
- Мой диалог: support@mydialogi.ru