IBA Platform logo

Как отправить первый код через умный шлюз

Пошаговый сценарий отправки первого кода через умный шлюз OTP — одиночное сообщение или каскад, API-ключ, имя отправителя, curl и проверка статуса

Коротко: один POST-запрос отправляет код — через один канал или каскадом. Платформа сама переключает каналы, если настроен каскад.

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

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

Что это

Пошаговый сценарий первого запуска: от получения API-ключа до проверки статуса доставки. К концу статьи вы отправите первый код через каскад WhatsApp → TTS → SMS или через один канал.

Детали параметров (successOn, timeout, cooldown, sendNextAfterFail) — в разделе API и интеграция.

Практические рекомендации по выбору этих параметров — в статье Как настроить каскад в умном шлюзе.

Два варианта отправки

Отправка может быть двух типов. Выберите подходящий — оба используют один эндпоинт /omnimessages.

ВариантКогда использоватьЧто в messages
Одиночное сообщениеЗадача решается одним каналом — например, только SMSОдно сообщение — один канал
КаскадНужна повышенная доставляемость — если первый канал не сработал, сообщение уйдёт по следующемуНесколько сообщений — цепочка каналов. SMS — последний

Доступные каналы. В умном шлюзе доступно 9 каналов OTP. Номера для поля channel — в таблице Какие каналы использовать для OTP.

Перед началом

  • Есть API-ключ с правами omni-api.
  • Есть имя отправителя со статусом Активно.
  • Настроен endpoint для вебхука (если нужны статусы доставки через push).
  • Вы определились — одиночное сообщение или каскад.

Шаги

1
Получите API-ключ

В личном кабинете: API Подключения → Создать API подключение.

Включите права omni-api и statistics. Выберите имя отправителя.

Как создать API-ключ →

2
Зарегистрируйте имя отправителя

Имя отправителя нужно для отправки сообщений по любому каналу. Дождитесь статуса Активно.

Как зарегистрировать имя отправителя →

3
Сформируйте запрос

URL: https://web.otpcod.ru/api/v1/omnimessages

Заголовки:

  • Content-Type: application/json
  • X-API-Key: <API-ключ>

Основные параметры:

ПараметрЧто указать
contactНомер получателя
isOtptrue — флаг, что это OTP
webhookURL для получения статусов (push)
cooldownВремя блокировки контакта при неудаче (секунды)
messagesМассив сообщений — одно или несколько
4
Отправьте запрос

Выберите вариант — одиночное сообщение или каскад. Примеры ниже.

5
Проверьте статус

Выберите способ — push (вебхук) или pull (GET /edrs).

Оба способа получения статусов →

Пример 1. Одиночное сообщение — только SMS

curl --location 'https://web.otpcod.ru/api/v1/omnimessages' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <API-ключ>' \
  --data-raw '{
    "contact": "79991234567",
    "isOtp": true,
    "webhook": "https://your-site.com/webhook",
    "messages": [
      {
        "channel": 1,
        "senderId": "<имя отправителя SMS>",
        "successOn": "delivered",
        "timeout": 60,
        "payload": {
          "text": "Ваш код: 1234"
        }
      }
    ]
  }'

Что происходит: платформа отправляет сообщение по SMS и ждёт delivered 60 секунд. Если статус получен — отправка завершена. Если нет — сообщение не доставлено, каскада нет.

Пример 2. Каскад — WhatsApp → TTS → SMS

curl --location 'https://web.otpcod.ru/api/v1/omnimessages' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <API-ключ>' \
  --data-raw '{
    "contact": "79991234567",
    "isOtp": true,
    "webhook": "https://your-site.com/webhook",
    "cooldown": 60,
    "messages": [
      {
        "channel": 4,
        "senderId": "<имя отправителя WhatsApp>",
        "successOn": "delivered",
        "timeout": 30,
        "payload": {
          "text": "Ваш код: 1234"
        }
      },
      {
        "channel": 11,
        "senderId": "<имя отправителя TTS>",
        "successOn": "delivered",
        "timeout": 45,
        "payload": {
          "text": "Ваш код 1234",
          "language": "ru",
          "repeat_count": 1
        }
      },
      {
        "channel": 1,
        "senderId": "<имя отправителя SMS>",
        "payload": {
          "text": "Ваш код: 1234"
        }
      }
    ]
  }'

Что происходит:

  1. Платформа отправляет сообщение по WhatsApp и ждёт delivered 30 секунд.
  2. Если статус получен — каскад завершён. Статус delivered финальный.
  3. Если не получен — переход на TTS, ожидание delivered 45 секунд.
  4. Если не получен — переход на SMS — последний канал цепочки.
  5. Если SMS тоже не доставлено — контакт блокируется на 60 секунд (cooldown).

Если от провайдера приходит статус «абонент недоступен», «номер не существует» или «отклонено» — платформа переключается на следующий канал немедленно, без ожидания таймаута.

Для OTP скорость критична. Пользователь ждёт код — если он не приходит за 30–60 секунд, он запросит новый. Поэтому таймауты для OTP измеряются в секундах, а не в минутах.

Подробнее о выборе таймаутов и других параметров — в статье Как настроить каскад в умном шлюзе.

Результат

Сообщение отправлено — одиночное или по каскаду. Статусы доставки вы получаете двумя способами на выбор — через push (вебхук) или pull (GET /edrs).

Частые проблемы

Причина: в запросе указано имя отправителя, которое не привязано к API-ключу.

Решение: откройте ключ в разделе API Подключения и добавьте нужное имя отправителя.

Как создать API-ключ →

Причина: статус, указанный в successOn, уже наступил. По умолчанию successOn = sent — переход не происходит.

Решение: явно укажите successOn: "delivered" для каждого сообщения каскада.

Как настроить каскад →

Причина: не указан webhook, или ваш сервер недоступен извне.

Решение: два варианта.

  1. Push: укажите webhook в запросе, в настройках имени отправителя или в настройках API-ключа. Убедитесь, что ваш сервер отвечает кодом 200 OK.
  2. Pull: запрашивайте статусы самостоятельно через GET /edrs.

Оба способа получения статусов →

См. также

Как работает умный шлюз

Режим, в котором вы генерируете код

Как настроить каскад

Практические рекомендации

Какие каналы использовать для OTP

9 каналов OTP и их номера в API

OMNI API — отправка кодов

Полное описание параметров

Форматы payload

JSON-примеры для каждого канала

Статусы сообщений

Push и pull

Как создать API-ключ

Создание и управление ключами

Как зарегистрировать имя отправителя

Имена для всех каналов

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