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

> **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.

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

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

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

## Что это

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

<Note>
**Детали параметров** (`successOn`, `timeout`, `cooldown`, `sendNextAfterFail`) — в разделе [API и интеграция](https://docs.mydialogi.ru/02-otp/08-api/otp-api-omni).

**Практические рекомендации** по выбору этих параметров — в статье [Как настроить каскад в умном шлюзе](https://docs.mydialogi.ru/02-otp/02-smart-gateway/otp-203-cascade-rules).
</Note>

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

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

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

<Note>
**Доступные каналы.** В умном шлюзе доступно 9 каналов OTP. Номера для поля `channel` — в таблице [Какие каналы использовать для OTP](https://docs.mydialogi.ru/02-otp/04-channels/otp-401-which-channels).
</Note>

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

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

## Шаги

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

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

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

[Как создать API-ключ →](https://docs.mydialogi.ru/06-reference/01-api/api-keys)

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

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

[Как зарегистрировать имя отправителя →](https://docs.mydialogi.ru/02-otp/03-for-developers/otp-301-sender-id)

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

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

**Заголовки:**

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

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

| Параметр | Что указать |
|---|---|
| `contact` | Номер получателя |
| `isOtp` | `true` — флаг, что это OTP |
| `webhook` | URL для получения статусов (push) |
| `cooldown` | Время блокировки контакта при неудаче (секунды) |
| `messages` | Массив сообщений — одно или несколько |

### 4. Отправьте запрос

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

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

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

[Оба способа получения статусов →](https://docs.mydialogi.ru/02-otp/08-api/otp-api-statuses)

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

```bash
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

```bash
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`).

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

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

Подробнее о выборе таймаутов и других параметров — в статье [Как настроить каскад в умном шлюзе](https://docs.mydialogi.ru/02-otp/02-smart-gateway/otp-203-cascade-rules).
</Note>

## Результат

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

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

### 400 Bad Request: sender not found

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

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

[Как создать API-ключ →](https://docs.mydialogi.ru/06-reference/01-api/api-keys)

### Каскад не переключается на следующий канал

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

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

[Как настроить каскад →](https://docs.mydialogi.ru/02-otp/02-smart-gateway/otp-203-cascade-rules)

### Не приходят статусы в мою программу

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

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

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

[Оба способа получения статусов →](https://docs.mydialogi.ru/02-otp/08-api/otp-api-statuses)

## См. также

<Columns cols={2}>
  <Card title="Как работает умный шлюз" icon="diagram-project" href="/02-otp/02-smart-gateway/otp-201-how-gateway-works">
    Режим, в котором вы генерируете код
  </Card>
  <Card title="Как настроить каскад" icon="arrow-progress" href="/02-otp/02-smart-gateway/otp-203-cascade-rules">
    Практические рекомендации
  </Card>
  <Card title="Какие каналы использовать для OTP" icon="share-nodes" href="/02-otp/04-channels/otp-401-which-channels">
    9 каналов OTP и их номера в API
  </Card>
  <Card title="OMNI API — отправка кодов" icon="paper-plane" href="/02-otp/08-api/otp-api-omni">
    Полное описание параметров
  </Card>
  <Card title="Форматы payload" icon="code" href="/02-otp/08-api/otp-api-omni-payload">
    JSON-примеры для каждого канала
  </Card>
  <Card title="Статусы сообщений" icon="signal" href="/02-otp/08-api/otp-api-statuses">
    Push и pull
  </Card>
  <Card title="Как создать API-ключ" icon="key" href="/06-reference/01-api/api-keys">
    Создание и управление ключами
  </Card>
  <Card title="Как зарегистрировать имя отправителя" icon="id-card" href="/02-otp/03-for-developers/otp-301-sender-id">
    Имена для всех каналов
  </Card>
</Columns>

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

- **OTP-коды:** support@otpcod.ru