Telegram docs

Telegram в Bridge сейчас доступен в двух режимах: user session через QR (telegram_qr_bridge) и bot token через Bot API (telegram_bot). Для QR-подключения platform admin заранее заполняет runtime settings telegram_api_id и telegram_api_hash; для bot mode достаточно токена из BotFather.

provider: telegramchannel_type: telegram_qr_bridge / telegram_botupdated: 2026-05-06

Подключение Inbound Outbound Проверено API notes

Connect

Как проходит подключение

Клиент подключает канал в кабинете. После статуса connected входящие события идут в webhook, а outbound API начинает принимать отправку в этот канал.

Шаг 1
Пользователь создает Telegram-канал в /my/channels.
Шаг 2
Для telegram_qr_bridge Bridge показывает QR-код; пользователь сканирует его в Telegram и при необходимости вводит 2FA password.
Шаг 3
Для telegram_bot пользователь вставляет bot token из BotFather, Bridge проверяет getMe, отключает внешний Telegram webhook и дальше сам забирает updates в polling-режиме.
Шаг 4
После успешного входа или подключения канал переходит в connected и начинает принимать inbound events.

Inbound

Что приходит из канала

Text

Работает

message.type = text, message.text содержит текст сообщения. Это уже работает и для telegram_qr_bridge, и для telegram_bot.

Photo, video, video_note

Частично

Для telegram_qr_bridge и telegram_bot Bridge сохраняет файл в storage и отдает его в attachments[] со signed URL. Для telegram_bot transport использует Bot API getFile, а полная live-smoke матрица по всем media типам остается отдельной задачей.

Audio, voice

Частично

Bridge нормализует тип, длительность и is_voice для telegram_qr_bridge и telegram_bot, если Telegram отдал metadata. Для bot mode это уже идет в тот же attachments[] contract.

Sticker, animation, document

Частично

File-like сообщения уже проходят в общий attachments[] contract и для telegram_qr_bridge, и для telegram_bot. Animated/video sticker semantics пока считаются best-effort поверх Bot API metadata.

Contact, share, location, poll, dice

Частично

Для telegram_bot Bridge теперь best-effort отдает message.type = contact | share | location | poll | dice вместо unsupported. Это пока не file/media contract: attachments[] остается пустым, а часть данных может приходить best-effort в message.text.

Sender metadata

Частично

username, first_name, last_name, display_name, avatar заполняются best-effort. phone обычно недоступен.

Outbound

Что можно отправлять через API

Для outbound используйте POST /v1/messages, bearer API key со scope messages:send, channel_id подключенного канала и provider chat id из inbound webhook.

Text

Работает

POST /v1/messages с content.type = text отправляет сообщение и в telegram_qr_bridge, и в telegram_bot.

Media

Частично

Для telegram_qr_bridge и telegram_bot content.type = media уже работает для photo, video, audio, voice, animation, file. Bridge скачивает attachments[].url и отправляет файл через Telegram user session или Bot API. Для telegram_bot voice дополнительно зависит от ограничений самого Telegram Bot API и в отдельных чатах может вернуться VOICE_MESSAGES_FORBIDDEN. Sticker outbound для Telegram пока не включен, поэтому общий статус остается partial.

Проверка

Что уже проверено

Проверено

QR login, 2FA password и сохранение connected-сессии после перелогина в Bridge.
Bot token connect: getMe, перевод telegram_bot в polling transport и хранение подключенного канала.
Inbound text через webhook message.inbound для telegram_qr_bridge и telegram_bot.
Inbound media через Bridge storage и signed /v1/attachments/:id URL для telegram_bot.
Outbound media через /v1/messages для telegram_bot: photo, video, audio, animation и file; voice в bot-mode зависит от ограничений Telegram Bot API и может быть отклонен.
Best-effort structured bot updates: contact, share, location, poll, dice в webhook message.inbound для telegram_bot.
Best-effort forwarded marker для telegram_bot через Bot API forward_origin.
Inbound media через Bridge storage и signed /v1/attachments/:id URL для telegram_qr_bridge.
Webhook sender/chat metadata: username, first_name, last_name, display_name, avatar best-effort.

Что осталось

Sticker outbound для Telegram пока не включен ни в telegram_qr_bridge, ни в telegram_bot.
Полная live-smoke матрица inbound media для telegram_bot.
Часть редких Telegram bot update-типов все еще может приходить как unsupported; Bridge теперь логирует их отдельно для дожима.
Webhook message.interaction для Telegram reactions пока не подключен.

API notes

Практические заметки для интеграции

Пример recipient

227657777

Для ответа используйте data.chat.external_id из inbound webhook.

Для telegram_bot поле message.forwarded заполняется best-effort из Bot API forward_origin или legacy forward fields, если Telegram реально отдал origin metadata.

В колонке TG общей матрицы учтены оба режима: telegram_qr_bridge и telegram_bot.

В поле подключения можно вставлять plain token, bot<token> или полный Bot API URL; Bridge сам нормализует значение перед getMe.

В production Bridge может отправлять Bot API запросы через внутренний VPN proxy bridge_vpn_gateway; внешний API contract от этого не меняется.

Для telegram_bot Bridge не ждет входящий webhook от Telegram: в production bot updates забираются самим Bridge через polling transport.

Для telegram_bot outbound media идет через Bot API методы sendPhoto, sendVideo, sendDocument, sendAudio, sendVoice, sendAnimation; для sendVoice Telegram может вернуть VOICE_MESSAGES_FORBIDDEN в конкретном чате.

attachments[].url всегда является ссылкой Bridge, а не прямой ссылкой Telegram.

Channels

Сравнить с другими каналами

Все API docs Telegram VK Community MAX QR Bridge WhatsApp QR Bridge