---
title: OMNI API — отправка сообщений
description: OMNI API Multi API — отправка одиночных сообщений и каскадов, параметры запроса, таблица каналов, отправка шаблонов
---
> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.
> **Коротко:** OMNI API — единый интерфейс для отправки сообщений. Поддерживает отправку одного сообщения и каскадную отправку с автоматическим переключением между каналами.
## Кому подходит
- Роль: Разработчик, Интегратор
- Уровень: Опытный
## Что такое OMNI API
OMNI API отправляет сообщения через единый эндпоинт. Не важно, какой канал вы используете — SMS, RCS, WhatsApp, Viber, Telegram и так далее, — структура запроса одна.
Два режима отправки:
- **Одиночное сообщение** — `POST /messages` — отправка через один канал.
- **Каскад** — `POST /omnimessages` — последовательная отправка через несколько каналов с автоматическим переключением.
## Эндпоинты
| Метод | Эндпоинт | Для чего |
|---|---|---|
| POST | `/messages` | Отправка одного сообщения |
| POST | `/omnimessages` | Каскадная отправка |
Полный URL: `https://web.multiapi.ru/api/v1/messages` и `https://web.multiapi.ru/api/v1/omnimessages`.
## Параметры запроса
| Поле | Тип | Обязательно | Что указать |
|---|---|---|---|
| contact | string | Да | Номер получателя с кодом страны, без «+» |
| channel | integer | Да | Номер канала (см. таблицу ниже) |
| senderId | string | Да | Имя отправителя из «Активы → Имена отправителей» |
| payload | object | Да* | Содержимое сообщения. Формат зависит от канала |
| template | object | Да* | Содержимое шаблона: `id` и `params` |
| webhook | string | Нет | URL для приёма статусов. Подробнее — [Вебхуки](/06-reference/01-api/api-webhooks) |
| clientInfo | string | Нет | Произвольное поле, сохраняется в EDR |
| isOtp | boolean | Нет | Если `true` — содержимое скрывается в EDR как OTP |
| successOn | string | Нет | Только для каскада. Статус успеха: `sent`, `delivered`, `seen`. По умолчанию `sent` |
| timeout | integer | Нет | Только для каскада. Секунды до перехода на следующий канал. По умолчанию 1200 (20 минут) |
| cooldown | integer | Нет | Только для каскада. Секунды блокировки контакта при неудаче. По умолчанию выключено |
| ttl | integer | Нет | Время жизни сообщения |
> *- нужен либо `payload`, либо `template`.
`isOtp: true` указывайте, только если сообщение содержит одноразовый код (OTP, 2FA, код верификации). Для обычных сообщений — не указывайте.
## Таблица каналов
| Номер | Канал |
|---|---|
| 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`.
## Отправка одного сообщения
Запрос `POST /messages` отправляет сообщение через один канал.
**Пример SMS:**
```bash
curl --location 'https://web.multiapi.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 по каналам](/03-multiapi/02-api/mapi-104-omni-payload).
## Каскадная отправка
Запрос `POST /omnimessages` принимает массив `messages` — по объекту на каждый канал.
Для каждого сообщения (кроме последнего) можно указать:
- **`successOn`** — статус, при котором сообщение считается успешным. Если он не наступит — платформа перейдёт к следующему сообщению.
- **`timeout`** — секунды ожидания `successOn`. По умолчанию 1200 (20 минут).
На верхнем уровне можно указать `cooldown` — секунды блокировки контакта при неудаче всего каскада.
**Пример: RCS → SMS с двумя шаблонами**
```bash
curl --location 'https://web.multiapi.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`. Во втором случае SMS уйдёт немедленно.
У каждого канала в каскаде может быть свой шаблон или произвольный текст через `payload`. Комбинации любые.
## Отправка шаблонов
Для отправки сообщения по шаблону используйте параметр `template` вместо `payload`.
| Поле | Тип | Обязательно | Что указать |
|---|---|---|---|
| `id` | integer | Да | ID шаблона из раздела «Активы» → «Шаблоны сообщений» |
| `params` | object | Да | Атрибуты шаблона. Если шаблон без переменных — передайте пустой объект `{}` |
**Пример отправки шаблона через RCS:**
```bash
curl --location 'https://web.multiapi.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 | Запрос принят. Тело содержит `error: false` и объект `data` |
| 400 | Ошибка параметров запроса |
| 401 | Неверный или отсутствующий API-ключ |
| 404 | Ресурс не найден |
| 500 | Внутренняя ошибка сервера |
**Пример успешного ответа:**
```json
{
"error": false,
"data": {
"channel": 4,
"transactionId": "95e3e0da-9684-4ba4-88a3-e9207ddeca05",
"messageId": "6719b5f4-36af-4fba-b111-49ff07f4f96b"
}
}
```
## Частые проблемы
**Причина:** неверный ID шаблона.
**Решение:** откройте раздел **Активы** → **Шаблоны сообщений**, скопируйте точный ID.
**Причина:** неверный ключ атрибута в `template.params`.
**Решение:** проверьте формат — например, `attribute.name`.
**Причина:** неверный или отсутствующий API-ключ.
**Решение:** проверьте заголовок `X-API-Key`.
**Причина:** в запросе указано имя отправителя, которое не привязано к этому ключу.
**Решение:** откройте ключ в разделе **API Подключения** и добавьте нужное имя отправителя.
**Причина:** статус, указанный в `successOn`, уже наступил — например, `sent`, а вы ждали `delivered`. По умолчанию `successOn` = `sent`, поэтому переход не происходит.
**Решение:** явно укажите `successOn: "delivered"` для каждого сообщения каскада.
## См. также
JSON-примеры для каждого канала
Запуск рассылок, шаблоны рассылок
Статусы сообщений и рассылок
HTTP-коды и форматы ответов
## Нужна помощь?
- Multi API: support@multiapi.ru