Telegram — документация AIKraft Agents

Интеграция с Telegram использует стандартный Bot API через токен бота, который вы создаёте с помощью @BotFather. Никакой привязки аккаунта не требуется — вы общаетесь с своим ботом, а бот управляет сессией Craft Agent.

Создание бота

Откройте @BotFather в Telegram. Найдите @BotFather и начните чат.
Создайте нового бота. Отправьте /newbot и следуйте инструкциям. Придумайте отображаемое имя и юзернейм (должен оканчиваться на bot, например my_craft_agent_bot).
Скопируйте токен. BotFather ответит строкой вида:
terminalbash
```
1234567890:ABCdefGHIjklMNOpqrsTUVwxyz-0123456789
```
Это ваш токен бота. Храните его как пароль — кто имеет токен, тот может выдать себя за вашего бота.
(Опционально) Отключите режим приватности для поддержки групп. Если хотите, чтобы бот работал в группах, отправьте /setprivacy → выберите бота → Disable. Для 1:1 использования (поддерживаемый и рекомендуемый режим) можно пропустить.

Только личные чаты. Шлюз отклоняет сообщения из групп и каналов на уровне адаптера. Даже если ваш бот добавлен в группу, только прямые сообщения с ботом могут управлять сессией.

Подключение в приложении

Откройте Settings → Messaging. В Craft Agent откройте Settings → Messaging. Вы увидите карточку для каждой поддерживаемой платформы.
Нажмите Connect на карточке Telegram. Откроется диалог, запрашивающий токен бота.
Вставьте токен и нажмите Test. Craft Agent вызывает эндпоинт getMe Telegram. При успехе вы увидите имя и юзернейм бота; при ошибке — сообщение Telegram дословно.
Нажмите Save. Токен сохраняется в вашем хранилище ключей workspace, и адаптер Telegram начинает прослушивание.

Первый диалог

Откройте бота в Telegram. Нажмите на ссылку t.me/<ваш_юзернейм_бота>, которую прислал BotFather, или найдите юзернейм бота в поиске.
Отправьте /new. Это создаёт новую сессию в вашем активном workspace и связывает чат с ней. Вы получите ответ:
terminalbash
```
Created "abc123" — you're connected. Just type to start.
```
Введите что-нибудь. Ваше сообщение пересылается агенту. Ответы приходят как сообщения в чат согласно вашему режиму ответа (по умолчанию: progress).

Вложения

Отправьте фото, документ, голосовое сообщение, видео или аудиофайл — шлюз загрузит файл, упакует его как FileAttachment и перешлёт в сессию вместе с вашей подписью.

Тип	Пересылается как
Фото	Изображение (в оригинальном разрешении)
Документ	Файл с оригинальным MIME-типом
Голосовое	Аудио (ogg/opus)
Видео	Видео
Аудио	Аудио

Жёсткий лимит: 20 МБ на вложение. Файлы большего размера или неуддачные загрузки вызывают видимый ответ в чате вместо тихого отбраковки.

Inline-кнопки

Telegram поддерживает inline-кнопки, поэтому команды вроде /bind отображаются как список нажимаемых последних сессий вместо пронумерованного текстового списка:

terminalbash

Recent sessions:
[ Morning standup ]
[ Release v0.8.10 ]
[ Debug session  ]

Нажмите кнопку → сессия привязана. Шлюз очищает клавиатуру на опубликованном сообщении, чтобы устаревшие кнопки не накапливались.

Управление доступом

Боты доступны для всех, кто знает юзернейм, поэтому по умолчанию новый workspace имеет доступ только для владельца через Telegram. Только отправители из списка разрешённых пользователей workspace могут выполнять команды до привязки (/new, /bind, /unbind, /status, /stop) или направлять сообщения в привязанную сессию.

Правило первого привязывания. Когда вы используете код привязки из нового workspace, ваш user_id в Telegram автоматически захватывается и добавляется как первый владелец. Вам не нужно вводить числовые идентификаторы — бот узнаёт их из вашего сообщения /pair.

Добавление других пользователей. Когда кто-то другой напишет боту, он получит ответ «Bot is private» и появится в разделе Settings → Messaging → Pending requests с кнопкой *Allow* в один клик. Никаких числовых идентификаторов не требуется.

Разрешительный список на уровне привязки. Каждая связь сессии-канала может переопределить политику workspace одним из трёх режимов:

Режим	Значение
Наследует workspace	По умолчанию. Использует список разрешённых пользователей workspace.
Пользовательский разрешительный список	Только явно отмеченные пользователи могут использовать эту привязку. Удобно для совместного доступа к одной сессии с гостем без предоставления доступа ко всему.
Открыто для всех	Любой в принятом чате может использовать эту привязку. Используйте только для действительно публичных ботов.

Миграция. Workspace, которые привязывали Telegram до появления управления доступом, остаются в режиме open, пока вы не нажмёте Lock down в Settings → Messaging. Существующие привязки сохраняют своё поведение, чтобы не нарушать работу.

Почему нет фильтрации групповых сообщений? Сообщения из групп и каналов отклоняются на уровне адаптера, если только вы не привязали супергруппу workspace. Внутри привязанной супергруппы правила на уровне отправителя применяются так же, как в личных сообщениях.

Вебхук vs длинный опрос

В приложении (Electron): адаптер использует длинный опрос (встроенный updater grammY). Публичный URL не нужен.
Удалённый сервер: адаптер использует вебхук. Настройте публичный URL (например, https://your-server.tld/telegram/webhook), зарегистрируйте его с помощью setWebhook, и Telegram будет отправлять обновления на него. Сервер проверяет заголовок X-Telegram-Bot-Api-Secret-Token.

См. Server → Headless для пути развёртывания вебхука.

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

Бот отвечает «No session bound to this chat»

Это ожидаемо при первом сообщении к свежему боту. Отправьте /new, чтобы создать и привязать сессию, или /pair <код>, чтобы использовать код привязки из приложения.

Тест завершается с ошибкой «401 Unauthorized»

Токен бота неверен или был отозван в BotFather. Выполните /token в @BotFather, чтобы получить новый, или /revoke, затем /newbot, если хотите начать с чистого листа.

Бот получает сообщения, но ничего не происходит

Проверьте, что workspace, в котором настроен бот, является активным в приложении. Каждый workspace имеет свою конфигурацию messaging — бот, зарегистрированный в workspace A, не будет управлять сессиями в workspace B.

Сообщения в группе не работают

По проекту — только личные сообщения с ботом могут управлять сессией. Сообщения из групп и каналов отклоняются на уровне адаптера.

Ответ «Attachment too large»

Bot API Telegram ограничивает загрузку файлов до 20 МБ. Вместо этого загрузите файл через встроенный выборщик вложений в приложении, или разделите его на части.