--- title: Отправка шаблонов через Omni API description: Отправка шаблонов через Omni API — параметр template, полная таблица параметров, примеры curl-запросов, коды ответов и вебхуки --- > **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, указав параметр `template` с ID шаблона и его параметрами. ## Кому подходит - Роль: Разработчик - Уровень: Опытный ## Что это Omni API — интерфейс для отправки сообщений через платформу. Он поддерживает два эндпоинта: - `POST /api/v1/messages` — отправка одного сообщения. - `POST /api/v1/omnimessages` — каскадная отправка с автоматическим переключением между каналами. В тело запроса добавляется параметр `template`. Он обязателен, если нужно отправить сообщение по шаблону. Для произвольного сообщения используется параметр `payload`. ## Эндпоинты | Метод | Эндпоинт | Для чего | |---|---|---| | POST | `/api/v1/messages` | Отправка одного сообщения | | POST | `/api/v1/omnimessages` | Каскадная отправка (несколько каналов) | ## Параметр template | Поле | Тип | Обязательно | Что указать | |---|---|---|---| | `id` | integer | Да | ID шаблона из раздела «Активы» → «Шаблоны сообщений» | | `params` | object | Да | Атрибуты шаблона. Если шаблон не содержит переменных — передайте пустой массив `{}` | `template` обязателен для отправки по шаблону. Для произвольного сообщения используйте `payload`. ## Как работает каскад В каскадном запросе (`/api/v1/omnimessages`) вы передаёте массив `messages` — по одному объекту на каждый канал. Для каждого сообщения (кроме последнего) можно указать: - **`successOn`** — статус, при котором сообщение считается успешным и переход на следующий канал не нужен. Возможные значения: `sent`, `delivered`, `seen`. По умолчанию `sent`. - **`timeout`** — время в секундах, в течение которого платформа ждёт наступления `successOn`. Если статус не наступил — отправляется следующее сообщение из массива. По умолчанию 1200 секунд (20 минут). На верхнем уровне запроса можно указать `cooldown` — время в секундах, на которое контакт блокируется, если последнее сообщение в каскаде не было успешным. По умолчанию блокировка выключена. Если от провайдера приходит статус о недоступности абонента, отсутствии номера или отклонении — переход на следующий канал происходит немедленно, не дожидаясь `timeout`. У каждого канала в каскаде может быть **свой** шаблон, **свой** набор `params`, а также произвольный текст через `payload`. Комбинации любые: шаблон + шаблон, шаблон + произвольный текст, произвольный текст + произвольный текст. ## Пример 1. Отправка через RCS ```bash curl --location 'https:///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" } } }' ``` ## Пример 2. Каскад RCS → SMS: два шаблона ```bash curl --location 'https:///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 секунд** (1 минута) **или** если от провайдера сразу придёт статус `failed` / `undeliverable`. Второй случай срабатывает немедленно, не дожидаясь таймаута. ## Пример 3. Каскад RCS-шаблон → SMS-текст ```bash curl --location 'https:///api/v1/omnimessages' \ --header 'Content-Type: application/json' \ --header 'X-API-Key: ' \ --data-raw '{ "contact": "", "webhook": "", "messages": [ { "channel": 2, "senderId": "", "successOn": "delivered", "timeout": 60, "template": { "id": , "params": { "attribute.phoneNumber": "112332" } } }, { "channel": 1, "senderId": "", "payload": { "type": "text", "text": "Резервное сообщение" } } ] }' ``` ## Таблица параметров запроса | Имя параметра | Тип | Обязательно | Примечание | |---|---|---|---| | X-API-Key | string | Да | Токен API из раздела «API Подключения». Передаётся в заголовке | | contact | string | Да | Номер получателя с кодом страны, без «+» | | channel | integer | Да | Канал отправки (см. таблицу ниже) | | senderId | string | Да | Имя отправителя из «Активы → Имена отправителей» | | payload | object | Да* | Содержимое сообщения. Формат зависит от канала | | template | object | Да* | Содержимое шаблона: `id` и `params` | | webhook | string | Нет | URL для приёма статусов. Если не указан — берётся из настроек имени отправителя или API-ключа | | clientInfo | string | Нет | Произвольное поле, сохраняется в EDR | | isOtp | boolean | Нет | Если `true` — содержимое сообщения скрывается в EDR как OTP | | successOn | string | Нет | Для omnimessages. Статус успеха: `sent`, `delivered`, `seen`. По умолчанию `sent` | | timeout | integer | Нет | Для omnimessages. Время в секундах до переключения на следующий канал. По умолчанию 20 минут (1200 с) | | cooldown | integer | Нет | Для omnimessages. Время в секундах для блокировки контакта при неудаче. По умолчанию выключено | | ttl | integer | Нет | Время жизни сообщения | > *- нужен либо `payload`, либо `template`. `isOtp: true` указывайте, только если сообщение содержит одноразовый код (OTP, 2FA, код верификации). В этом случае в EDR текст сообщения будет заменён на безопасный для чтения. Для обычных сообщений (рассылки, уведомления, диалоги) — не указывайте. ## Таблица каналов | Номер | Канал | |---|---| | 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 | ## Что в ответе | Код | Что означает | |---|---| | 202 Accepted | Запрос принят. Тело содержит `error: false` и объект `data` с `channel`, `transactionId`, `messageId` | | 400 | Ошибка параметров запроса | | 401 | Неверный или отсутствующий API-ключ | | 404 | Ресурс не найден | | 500 | Внутренняя ошибка сервера | **Пример успешного ответа:** ```json { "error": false, "data": { "channel": 4, "transactionId": "95e3e0da-9684-4ba4-88a3-e9207ddeca05", "messageId": "6719b5f4-36af-4fba-b111-49ff07f4f96b" } } ``` 202 Accepted означает, что платформа приняла сообщение. Факт доставки приходит асинхронно через вебхук. ## Вебхуки Вебхук используется для получения статусов отправки, доставки и прочтения, а также ответов получателя. Вебхук определяется в следующем порядке (берётся первое непустое значение): 1. Поле `webhook` в теле запроса. 2. Вебхук, настроенный для имени отправителя. 3. Вебхук, настроенный для 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" } } ``` **Возможные статусы:** `sent`, `failed`, `delivered`, `undeliverable`, `displayed`, `unknown`. ## Частые проблемы **Причина:** неверный ID шаблона. **Решение:** откройте раздел **Активы** → **Шаблоны сообщений**, скопируйте точный ID. **Причина:** неверный ключ атрибута в `template.params`. **Решение:** проверьте формат — например, `attribute.name`. **Причина:** шаблон не получил статус «Одобренный». **Решение:** дождитесь одобрения в разделе «Активы» → «Шаблоны WhatsApp». **Причина:** неверный или отсутствующий API-ключ. **Решение:** проверьте заголовок `X-API-Key`. **Причина:** неверный эндпоинт или ID ресурса. **Решение:** проверьте URL и ID шаблона. ## Что дальше Создание шаблона в разделе «Активы» Базовый пример отправки через Omni API Все параметры Multi API Создание и управление ключами ## Нужна помощь? - OTP-коды: support@otpcod.ru - Multi API: support@multiapi.ru - Мой диалог: support@mydialogi.ru