IBA Platform logo

Что такое Telegram Gateway

Telegram Gateway — канал для отправки кодов верификации через Telegram по API

Коротко: Telegram Gateway — канал для отправки кодов верификации через Telegram. Работает через API, без установки бота пользователем.

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

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

Что это

Telegram Gateway — официальный сервис Telegram для отправки кодов аутентификации. Пользователь получает код от Telegram — без необходимости устанавливать отдельного бота и подписываться.

Используется только для кодов верификации. Для двусторонней коммуникации — используйте Telegram bot →.

Telegram Gateway не доступен для отправки из личного кабинета. Канал работает только через API — интеграцию с программой клиента.

Отправить код через Telegram Gateway из интерфейса рассылки нельзя.

Как это работает

1
Программа клиента вызывает API

Ваша программа отправляет запрос на платформу через API — указывает канал 8 (Telegram Gateway).

2
Платформа передаёт запрос в Telegram

Сервис передаёт данные в Telegram Gateway.

3
Получатель получает код

Telegram отправляет код получателю — без установки бота и подписки.

4
Получите статусы доставки

Статусы приходят двумя способами:

  • Push (вебхук) — платформа сама отправляет статус на ваш URL.
  • Pull (запрос к API) — вы запрашиваете статусы самостоятельно через GET /edrs.

Как получать статусы:

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

  • Канал Telegram Gateway подключён к вашему аккаунту — обратитесь в поддержку сервиса.
  • У вас есть API-ключ с правами omni-api — API-ключи →.
  • У вас есть имя отправителя Telegram Gateway со статусом Активно — Имя отправителя для Telegram →.
  • Ваша программа готова к интеграции с API.

Что содержит

ПолеОбязательностьЧто указать
codeОсновной способГотовый код, который нужно отправить — 4–8 цифр
code_lengthДополнительноДлина генерируемого кода — 4–8
ttlОпциональноВремя жизни кода в секундах — 30–3600
isOtpРекомендуетсяФлаг, что сообщение содержит OTP
webhookОпциональноURL для получения статусов доставки

Основной способ — передать готовый code. Вы генерируете код на своей стороне и отправляете его получателю через Telegram Gateway.

Дополнительный способ — code_length. Telegram сам генерирует код указанной длины.

Как подключить

1
Обратитесь в поддержку сервиса

Напишите на почту поддержки вашего сервиса с запросом на подключение Telegram Gateway.

Контакты поддержки →

2
Дождитесь подключения канала

Поддержка подключит канал к вашему аккаунту и зарегистрирует имя отправителя Telegram Gateway.

3
Создайте API-ключ

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

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

API-ключи →

4
Интегрируйте отправку в программу

Используйте API-ключ в запросах — см. пример ниже.

Обзоры API:

Как отправить код

Эндпоинт: POST /api/v1/messages

Заголовки:

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

Основной способ — готовый код

Вы генерируете код на своей стороне и передаёте его в запросе.

{
  "channel": 8,
  "contact": "905518709790",
  "senderId": "transit",
  "isOtp": true,
  "payload": {
    "code": "12345",
    "ttl": 300
  }
}

Дополнительный способ — код генерирует Telegram

Если не хотите генерировать код сами — передайте длину, и Telegram сгенерирует код автоматически.

{
  "channel": 8,
  "contact": "905518709790",
  "senderId": "transit",
  "isOtp": true,
  "payload": {
    "code_length": 5,
    "ttl": 300
  }
}

Что здесь что:

ПолеЧто означает
channel: 8Канал Telegram Gateway
contactНомер получателя
senderIdИмя отправителя Telegram Gateway
isOtp: trueФлаг, что сообщение содержит OTP — содержимое скрыто в EDR
codeГотовый код для отправки — основной способ
code_lengthДлина генерируемого кода — дополнительный способ
ttlВремя жизни кода

Если указан code — code_length игнорируется.

Если code не указан — Telegram использует code_length и генерирует код сам.

Отозвать верификационное сообщение

Эндпоинт POST /messages/revoke позволяет отозвать ранее отправленное верификационное сообщение Telegram Gateway.

Эндпоинт: POST /messages/revoke

{
  "messageId": "019372a1-d252-7908-9216-028bd36c7af1"
}

Что вернётся:

ПолеЧто означает
successtrue — сообщение отозвано
message_idID отозванного сообщения
errorОписание ошибки, если есть

Обзоры API:

API и интеграция

Для Telegram Gateway доступны эндпоинты:

ЭндпоинтЧто делает
POST /messagesОтправка кода
POST /messages/verificationПроверка статуса верификации
POST /messages/revokeОтозвать верификационное сообщение Telegram Gateway

Подробное описание эндпоинтов — в обзорах API:

Результат

Канал Telegram Gateway подключён, API-ключ создан, программа интегрирована. Коды можно отправлять.

Сколько это стоит? Telegram Gateway тарифицируется за сообщение. Подробнее: Обзор тарифов →.

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

Причина: Telegram Gateway не активирован для вашего аккаунта.

Решение: обратитесь в поддержку сервиса — подключение выполняется вручную.

Контакты поддержки →

Причина: неверный senderId, или у получателя нет Telegram.

Решение: проверьте имя отправителя — оно должно быть Активно, и убедитесь, что получатель пользуется Telegram.

Имя отправителя для Telegram →

Причина: значение ttl вне допустимого диапазона.

Решение: используйте значения от 30 до 3600 секунд.

Причина: значение code_length вне допустимого диапазона.

Решение: используйте значения от 4 до 8.

Причина: в запросе одновременно указаны оба параметра.

Решение: оставьте только один. Параметр code_length игнорируется, если указан code.

Причина: не установлен флаг isOtp: true.

Решение: добавьте isOtp: true — содержимое будет скрыто в EDR.

Причина: не указан webhook URL.

Решение: укажите webhook URL в настройках отправки или запрашивайте статусы через GET /edrs.

Вебхуки →

Причина: неверный или отсутствующий API-ключ.

Решение: проверьте заголовок X-API-Key и права ключа.

Ошибка 401 →

См. также

Что такое Telegram bot

Двусторонняя коммуникация через бота

Имя отправителя для Telegram

Регистрация имени отправителя

Обзор API OTP-кодов

OMNI API, Broadcasts API, 2FA

Обзор API Multi API

OMNI API и Broadcasts API

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