Интеграция с Telegram

Подключите своего агента к Telegram и позвольте пользователям общаться с ним прямо в приложении Telegram.

Обзор

Интеграция с Telegram предоставляет:

• Потоковые ответы в реальном времени (Bot API 9.5 sendMessageDraft с fallback на edit-message)
• Голосовые сообщения автоматически транскрибируются через Whisper
• Форматирование MarkdownV2, которое всегда отображается корректно
• Deep-link кампании с настраиваемым приветствием и предлагаемыми ответами
• Реакции эмодзи в одно нажатие с классификацией тональности
• Встроенные slash-команды (/start, /help, /reset, /new)
• Личные сообщения и групповые чаты (отдельные сессии для каждого пользователя в группах)
• Встроенный магазин в Telegram — многостраничный каталог товаров, AI-чат по каждому товару и лёгкий приём заказов, всё внутри Telegram (бесплатно на любом тарифе)
• Опциональный Telegram Business co-pilot для Premium-пользователей (отдельная интеграция)
• Saba on Telegram для операторов (отдельная интеграция)

Предварительные требования

• Аккаунт в Telegram
• Доступ к BotFather (инструмент Telegram для создания ботов)

Шаги настройки

1. Создайте Telegram-бота

1. Откройте Telegram и найдите @BotFather
2. Начните чат и отправьте /newbot
3. Следуйте инструкциям:
   • Введите имя вашего бота (например, “My Support Bot”)
   • Введите имя пользователя (должно заканчиваться на “bot”, например, “mysupportbot”)
4. BotFather выдаст вам Bot Token — сохраните его в безопасном месте

2. Подключение к Cuneiform Chat

1. Перейдите в Integrations в боковой панели
2. Откройте карточку Telegram
3. Вставьте ваш Bot Token
4. Нажмите Connect

3. Настройте бота

Дополнительные настройки бота через BotFather:

• /setdescription — описание назначения бота
• /setabouttext — информация в профиле бота
• /setuserpic — аватар вашего бота

4. Протестируйте бота

1. Найдите бота в Telegram по его имени пользователя
2. Начните диалог с помощью /start
3. Отправьте сообщение и убедитесь, что получаете ответ

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

User sends message → Telegram → Cuneiform Chat → Agent processes → Response sent back

Сообщения обрабатываются в реальном времени. Агент ищет информацию в вашей базе знаний и генерирует ответы на основе вашей конфигурации.

Возможности

Потоковые ответы в реальном времени

Ответ бота приходит за миллисекунды и растёт по мере того, как ваш агент думает — используя нативный sendMessageDraft (Bot API 9.5) там, где это поддерживается, и throttled fallback на edit-message в остальных случаях. Больше никаких 5–15 секунд тишины между вопросом и ответом.

Голосовые сообщения

Голосовые заметки, отправленные боту, транскрибируются через Whisper и обрабатываются как если бы они были набраны текстом. Язык определяется автоматически по контексту разговора, поэтому короткие записи на любом языке остаются точными. Лимит — 2 минуты на заметку. Доступно на всех планах, включая бесплатный trial.

Форматирование MarkdownV2

Жирный, курсив, блоки кода, списки и ссылки отображаются именно так, как задумал ваш агент — никаких сломанных markdown или лишних звёздочек. Экранирование централизовано на платформе, поэтому каждый ответ остаётся чистым. MarkdownV2 — режим по умолчанию; HTML-режим доступен per-integration при необходимости.

Deep-link и реферальные кампании

Создавайте ссылки t.me/your-bot?start=your-code из карточки интеграции. Каждый код может содержать настраиваемое приветственное сообщение и до трёх предлагаемых ответов. Click-through, уникальные пользователи и conversion в разговоры отслеживаются по каждому коду — полезно для рекламных кампаний, QR-кодов и multi-channel атрибуции.

Реакции эмодзи в одно нажатие

Пользователи реагируют на сообщения бота с помощью 👍, ❤, 😡 или любого эмодзи. Бот отвечает с правильным тоном через короткие reaction-acknowledgement реплики. Встроенный классификатор сопоставляет любое эмодзи с позитивным, негативным или нейтральным сигналом, который вы можете проанализировать позже. Сейчас активно в DM.

Slash-команды

Интеграция регистрирует список команд по умолчанию в Telegram при подключении, поэтому пользователи видят /start, /help, /reset и любые ваши кастомные команды в нативном меню автодополнения Telegram. /start, /help, /reset и /new обрабатываются inline без затрат на AI. Перетаскивайте для изменения порядка; до 32 записей.

Личные сообщения

Пользователи общаются с ботом один на один для приватных диалогов поддержки. У каждого пользователя своя сессия.

Групповые чаты

Добавьте бота в групповые чаты:

1. Добавьте бота в группу
2. Сделайте его администратором (для полного доступа к сообщениям — см. Group Privacy ниже)
3. Пользователи упоминают бота (@your_bot) или отвечают на его сообщения

У каждого пользователя в группе свой собственный thread разговора — бот не смешивает сессии разных участников. Forum-topic группы поддерживаются; threads остаются привязанными к своему topic.

Магазин в Telegram

К каждому подключённому Telegram-боту прилагается встроенный магазин — отполированный многостраничный встроенный сайт, который открывается внутри Telegram, когда конечные пользователи нажимают на кнопку меню рядом с полем ввода сообщения. Карточки товаров, галереи, видео, тематически оформленные страницы, AI-чат по каждому товару и лёгкий приём заказов, который передаётся живому оператору в ваш Inbox — всё без установки приложения и без отдельного сайта.

Автоматически связывается при подключении: кнопка chat-menu открывает магазин с надписью “Shop”, если вы опубликовали товар, или “Open” в остальных случаях. Доступно на любом тарифе, включая бесплатный trial.

Полное руководство по функции — конструктор, блоки, темы оформления, чат по товару, CTA-кнопки заказа, лимиты тарифов — на отдельной странице:

→ Магазин в Telegram — полная настройка, справочник блоков и клиентский флоу.

Небольшая панель поддержки Help Center закреплена в конце меню страниц магазина для быстрых FAQ-ответов и шорткатов «спросить бота». Большинство магазинов не делают на неё большой ставки — товары и CTA-кнопки заказа сами отвечают на вопросы по покупке прямо в магазине. Записи создаются из меню из трёх точек на карточке бота → Help Center (до ~50 записей, перетаскивание для изменения порядка, ~5 минут серверного кэша).

Telegram Business co-pilot

Пользователи Telegram уровня Premium могут позволить вашему боту отвечать на DM в их личном аккаунте через режим Telegram Business. Бот отвечает через business_connection_id Premium-пользователя, поэтому контакты видят то, что выглядит как собственные ответы Premium-пользователя — полезно для основателей, креаторов и небольших команд, которым весь день пишут DM на личные аккаунты.

Настройка — отдельная интеграция в админ-панели (“Telegram Business co-pilot”). Ключевые инварианты:

• 1 бот = 1 customer agent. Telegram-бот может указывать только на один webhook за раз — вы не можете делить бота с обычной интеграцией Telegram или Saba on Telegram. Создайте свежего BotFather-бота для режима Business.
• Требуется переключатель Business Mode в BotFather. Без него Premium-пользователи увидят “this bot doesn’t support Telegram Business yet” при добавлении бота. Включите его в Bot Settings → Business Mode.
• N Premium-пользователей на интеграцию. Каждый привязывается один раз через /start <code> в обычном DM с ботом.
• Только DM. Business-соединения не покрывают групповые чаты.
• Manual takeover работает автоматически. Когда Premium-пользователь сам печатает ответ, бот ставит этот чат на паузу на скользящее окно, чтобы не говорить поверх живого разговора.
• Connection-level kill switch. Переключите “Disable auto-reply” на карточке интеграции, чтобы поставить бота на паузу для всех привязанных Premium-пользователей без отключения.

См. Connect Business bot в разделе Telegram Business co-pilot страницы Integrations админ-панели для полного плейбука настройки.

Saba on Telegram

Операторы также могут общаться с Saba (платформенным ассистентом) из выделенного Telegram-бота. Те же права и доступ к данным, что и в админ-панели — полезно, когда вы вдали от ноутбука и нужно проверить статистику агентов, billing или недавнюю активность.

Две поверхности над одним каналом:

• DM-бот — текстовые ответы в обычном Telegram DM, с inline-кнопками действий, которые deep-link перенаправляют на нужную страницу админ-панели (?from=saba_telegram для атрибуции).
• Saba Mini App — более богатая поверхность чата внутри Telegram по адресу saba-mini.cuneiform.chat с историей разговоров, деталями вызовов инструментов, голосовым вводом в браузере и экспортом в markdown. Каждый ответ в DM сопровождается inline-кнопкой “Open in Mini App” для переключения поверхностей в середине разговора.

Настройка — со стороны администратора: подключите свежего BotFather-бота в разделе “Saba on Telegram” в Integrations. Затем каждый член организации привязывает свой личный аккаунт с помощью 10-минутного кода.

См. Платформенный ассистент → Из Telegram для пользовательского опыта.

Команды бота

Вы можете настроить пользовательские команды через BotFather:

Устранение неполадок

Бот не отвечает

1. Убедитесь, что Bot Token введён правильно
2. Проверьте, что интеграция подключена в Cuneiform Chat
3. Убедитесь, что агент правильно настроен
4. Сначала протестируйте агента в Playground

Проблемы с токеном

Если вам нужен новый токен:

1. Перейдите к BotFather
2. Отправьте /mybots → выберите бота → API Token → Revoke
3. Обновите новый токен в Cuneiform Chat

Проблемы с групповым чатом

• Убедитесь, что у бота есть права администратора
• Проверьте настройки приватности через BotFather (/setprivacy)

Безопасность

• Bot Token зашифрованы и хранятся в защищённом виде
• Диалоги обрабатываются через защищённые соединения

Отключение

Чтобы удалить интеграцию с Telegram:

1. Перейдите в Integrations в боковой панели
2. Откройте карточку Telegram и нажмите Disconnect

Это остановит ответы бота, но не удалит самого Telegram-бота. При необходимости удалите его через BotFather.