Документация › Каналы › Подключить Telegram

Подключить Telegram-бота

Самый быстрый и безопасный канал: создаёшь бота в @BotFather, копируешь токен, вставляешь в кабинет — и бот отвечает клиентам в Telegram. Подключение бесплатное, без риска бана.

⏱ 8 мин · 👤 для владельца и оператора · 🟢 live

За 30 секунд:

• Напиши @BotFather в Telegram → /newbot → получи токен вида 1234567:AAE….
• Кабинет → проект → «Каналы» → секция Telegram → вставь токен → «Подключить».
• Один бот = один проект. Подключение бесплатно (платишь только за ответы бота с баланса).
• Токен хранится в зашифрованном виде, входящие проверяются секретом — чужой к боту не подключится.
• Отключение не трогает токен в @BotFather и сохраняет историю, лиды и дожимы.

Зачем это нужно

Telegram — второй канал платформы рядом с WhatsApp. В отличие от WhatsApp, здесь используется официальный Bot API — значит, нет риска бана номера, нет «прогрева», нет подписки за сам канал. Это самый простой способ запустить бота в бою за пару минут.

Мозг у бота общий: тот же промпт, база знаний, функции и дожимы работают в Telegram точно так же, как в WhatsApp (см. Обзор каналов).

Шаг 1. Создать бота в @BotFather

1. Открой Telegram, найди @BotFather (официальный бот Telegram с синей галочкой).
2. Отправь команду /newbot.
3. Придумай имя бота (показывается в шапке чата) и username (должен заканчиваться на bot, например my_shop_bot).
4. BotFather пришлёт токен — длинную строку вида 1234567:AAExxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

🔒 Токен — это пароль от бота. Никому его не показывай. Если случайно засветил — в @BotFather командой /revoke выпусти новый, старый перестанет работать.

Шаг 2. Подключить в кабинете

1. Меню проекта → «Каналы».
2. В секции Telegram вставь токен в поле (оно скрыто как пароль).
3. Нажми «Подключить».

Что происходит за кулисами (/api/projects/<id>/telegram/connect):

• токен проверяется по формату ^\d+:[A-Za-z0-9_-]+$ (цифры, двоеточие, буквы/цифры) — если не подходит, увидишь «Неверный формат токена. Скопируйте токен из @BotFather без пробелов и лишних символов»;
• платформа дёргает Telegram getMe — убеждается, что бот живой, и подтягивает его @username;
• вызывается `setWebhook` — платформа говорит Telegram «слать все сообщения сюда»; при этом задаётся секретный токен (случайный), которым Telegram подписывает каждый входящий запрос;
• проект из статуса «черновик» автоматически переходит в «активен» — бот сразу в эфире.

После успеха — тост «Telegram бот подключён!», в секции отображается @username бота.

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

Шаг 3. Проверить

Рядом есть кнопка «Проверить подключение» (/api/projects/<id>/telegram/status):

• «Бот подключён и работает» — всё ок;
• «Бот не отвечает. Проверьте токен.» — токен отозван или неверен, переподключи.

Дальше открой своего бота в Telegram (по его @username), напиши ему — он должен ответить как настроен в промпте.

⚠️ Если бот молчит — проверь, что ИИ включён и на балансе есть деньги: Telegram-подключение бесплатно, но каждый ответ бота списывает токены с баланса проекта, как и в WhatsApp. → Бот не отвечает

Что умеет бот в Telegram

• Текст — основной режим.
• Голосовые — расшифровываются в текст, бот отвечает по смыслу.
• Видео и видео-кружки — звуковая дорожка расшифровывается, бот отвечает по содержанию.
• Фото — бот «видит» картинку (описание изображения) и реагирует. Подпись под фото учитывается как вопрос клиента.
• Альбомы (несколько фото разом) — собираются в один запрос, бот отвечает одним сообщением, а не на каждое фото отдельно.
• Файлы — принимаются до 20 МБ.
• Пересланные сообщения — бот понимает, что это форвард, и учитывает откуда.
• Стикеры — бот считывает эмодзи стикера как настроение и отвечает по-человечески (раньше отвечал «не умею со стикерами»).
• Telegram Business — поддерживаются бизнес-сообщения (если у тебя Telegram Business-аккаунт, бот отвечает и там).
• Кнопки под ответом (опция) — бот может предлагать клиенту нажимаемые кнопки выбора (записаться / узнать цену / да-нет). Включается в Настройки → Разбивка ответов → «Кнопки под ответом бота». Нажатие кнопки бот воспринимает как ответ клиента и продолжает диалог.
• Группы и супергруппы (опция) — бот может отвечать в групповых чатах, но только когда к нему обращаются: упомянули через @имя_бота или ответили на его сообщение. На остальную переписку он не реагирует. Включается в Настройки → Разбивка ответов → «Отвечать в Telegram-группах».
• Реакции (👍/❤️) — фиксируются как сигнал настроения клиента (бот на них не отвечает, чтобы не спамить).
• Меню команд — при подключении у бота автоматически появляются команды /start и /help (кнопка «/» в Telegram).

Всё это — тот же конвейер, что и в других каналах: функции, база знаний, лиды, дожимы.

Кампании и рассылки

Когда бот подключён, в разделе Каналы → Telegram появляется «Ссылка для рекламной кампании»: вводишь название кампании (например instagram_jan) — получаешь ссылку вида t.me/твойбот?start=instagram_jan. Дай её в рекламе/постах: кто перейдёт и нажмёт «Старт», попадёт в Аналитику → раздел «Кампании» — увидишь по каждой кампании диалоги, лиды, конверсию и выручку. Это как реклама-атрибуция для WhatsApp, только для Telegram-ссылок.

Рассылки (раздел «Рассылки» в меню проекта, нужны права администратора) — отправь сообщение сразу всей своей базе контактов. Только Telegram: массовая отправка в WhatsApp грозит баном номера, поэтому рассылки работают исключительно по Telegram-контактам. Что умеет рассылка:

• Кнопки под сообщением — добавь к рассылке нажимаемые кнопки (ответ боту или ссылка). Рядом — живой предпросмотр, как сообщение увидит клиент.
• Сужение базы — можно сузить по статусу лида, тегу или рекламной кампании (кто пришёл по конкретной deep-link ссылке). Рядом сразу показывается сколько контактов попадёт под условия — видно охват ещё до отправки.
• Запланировать на потом — выбери «Запланировать» и укажи дату/время; рассылка сама уйдёт в нужный момент (до этого её можно отменить).
• Бережная доставка — сообщения уходят постепенно (анти-бан), а кто написал боту «стоп»/«отписаться» — исключается автоматически.
• В истории видно, сколько отправлено, сколько ошибок, и можно остановить рассылку (или запланированную, и идущую) на ходу.

Профиль бота. В разделе Каналы → Telegram (когда бот подключён) есть свёрнутый блок «Профиль бота в Telegram» — прямо из кабинета можно задать короткое описание (строка под именем бота) и описание (текст «Что умеет этот бот?», который клиент видит в пустом чате до первого сообщения). Не нужно открывать @BotFather.

Кнопки и аналитика вовлечённости. Если включены кнопки под ответом, оператор видит их прямо в диалоге, а когда клиент нажимает кнопку — в переписке появляется пометка «🔘 Нажал кнопку» (видно, что это нажатие, а не набранный текст). В Аналитике появляется блок «Вовлечённость в Telegram»: показы кнопок, нажатия, кликабельность (CTR), какие кнопки нажимают чаще, реакции клиентов (👍/❤️) и разбивка диалогов на личные и групповые.

Отключить Telegram

Секция Telegram → «Отключить». Подтверждение предупредит: «Бот перестанет отвечать клиентам в Telegram. История диалогов, лиды и подписчики drip сохранятся. Подключить можно тот же или новый бот — токен в @BotFather не пострадает.»

При отключении (/api/projects/<id>/telegram/disconnect) платформа снимает вебхук в Telegram (deleteWebhook) и очищает все Telegram-поля проекта. Сам бот в @BotFather остаётся — токен живой, можно переподключить когда угодно.

🔧 Под капотом

Для технически любопытных — как устроено хранение и безопасность (по коду):

• Шифрование токена. telegram_bot_token хранится зашифрованным (AES-256-GCM, ключ ENCRYPTION_KEY, префикс enc:). В открытом виде в базе токена нет.
• Дедуп. Рядом лежит telegram_bot_token_hash (SHA-256) — по нему за один запрос проверяется, не привязан ли этот бот к другому проекту. Если привязан — «Этот бот уже привязан к другому проекту. Создай нового бота в @BotFather или отключи от старого проекта.»
• Проверка входящих. Telegram шлёт обновления на /api/webhook/telegram/<projectId> с заголовком x-telegram-bot-api-secret-token. Платформа сравнивает его с сохранённым секретом timing-safe сравнением (safeStringEqual); не совпал — 401, сообщение отклонено. Так чужой не сможет слать боту фейковые апдейты.
• Подписанные типы апдейтов. Вебхук слушает: message, edited_message, callback_query, message_reaction, business_connection, business_message, edited_business_message, deleted_business_messages.
• Лимиты. Подключение/отключение — 5 запросов / 60 сек (admin-роль). Входящий вебхук — 60 запросов / 60 сек на проект. Токен в запросе — до 200 символов.
• Медиа без утечки токена. Файлы Telegram сохраняются как tg-file://…, чтобы токен бота не попал в ссылку.
• Ошибки подключения (понятные RU-тексты): Telegram не принял токен → «Telegram не принял токен. Скопируй токен заново — целиком, от @BotFather, без пробелов.»; Telegram недоступен → «Telegram сейчас недоступен. Попробуй через минуту.»; иное → «Не удалось подключить бот. Повтори ещё раз, если повторится — напиши в саппорт.»

💬 Простыми словами

Telegram — самый лёгкий способ запустить бота. Идёшь к @BotFather (это «фабрика ботов» внутри самого Telegram), пишешь /newbot, придумываешь имя — и он выдаёт тебе токен, такой длинный код. Этот код ты вставляешь в кабинете в разделе «Каналы» и жмёшь «Подключить». Всё — бот ожил, отвечает всем, кто ему напишет в Telegram.

Никакого риска, в отличие от WhatsApp: тут не нужен «прогретый номер», никто никого не банит, и за само подключение денег не берут. Платишь только за работу бота — за его ответы, как везде.

Токен — это как пароль, держи его при себе. Если что-то пошло не так, всегда можно нажать «Проверить подключение»: бот либо «работает», либо просит обновить токен. А отключение ничего не ломает — история переписок, лиды и дожимы остаются на месте, и бот в @BotFather никуда не девается.

Дальше: → Функции (инструменты бота)
Связано: Обзор каналов · Подключить WhatsApp · Системный промпт · Биллинг
Не получилось? → Бот не отвечает