Telegram

Подключение PRX к Telegram через официальный Bot API с поддержкой ЛС, групп, потоковых ответов и медиа-вложений.

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

• Аккаунт Telegram
• Токен бота от @BotFather
• Telegram user ID или имена пользователей разрешённых пользователей

Быстрая настройка

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

1. Откройте Telegram и напишите @BotFather
2. Отправьте /newbot и следуйте подсказкам, чтобы назвать бота
3. Скопируйте токен бота (формат: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

2. Конфигурация

Добавьте следующее в файл конфигурации PRX:

[channels_config.telegram]
bot_token = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
allowed_users = ["123456789", "your_username"]

Если allowed_users оставлен пустым, PRX переходит в режим сопряжения и генерирует одноразовый код привязки. Отправьте /bind <code> из вашего аккаунта Telegram для привязки.

3. Проверка

prx channel doctor telegram

Справочник конфигурации

Поле	Тип	По умолчанию	Описание
bot_token	String	обязательный	Токен Telegram Bot API от @BotFather
allowed_users	[String]	[]	Telegram user ID или имена пользователей. Пусто = режим сопряжения. "*" = разрешить всем
stream_mode	String	"none"	Режим потоковой передачи: "none", "edit" или "typing". Режим edit прогрессивно обновляет сообщение ответа
draft_update_interval_ms	u64	500	Минимальный интервал (мс) между редактированиями черновика для предотвращения ограничений частоты
interrupt_on_new_message	bool	false	Если true, новое сообщение от того же отправителя отменяет текущий запрос
mention_only	bool	false	Если true, отвечать только на @-упоминания в группах. ЛС обрабатываются всегда
ack_reactions	bool	наследуется	Переопределение глобальной настройки ack_reactions. Откатывается к [channels_config].ack_reactions, если не задано

Возможности

• Личные и групповые сообщения — отвечает в ЛС и групповых беседах
• Потоковые ответы — прогрессивное редактирование сообщения показывает ответ по мере генерации
• Режим сопряжения — безопасная привязка одноразовым кодом при отсутствии настроенных разрешённых пользователей
• Медиа-вложения — обработка документов, фотографий и подписей
• Разбиение длинных сообщений — автоматическое разбиение ответов, превышающих лимит Telegram в 4096 символов, по границам слов
• Подтверждающие реакции — реакция на входящие сообщения для подтверждения получения
• Транскрипция голосовых сообщений — транскрипция голосовых сообщений при настроенном STT

Ограничения

• Telegram ограничивает текстовые сообщения 4096 символами (PRX автоматически разбивает более длинные)
• Опрос Bot API вносит небольшую задержку по сравнению с режимом вебхуков
• Боты не могут инициировать разговоры; пользователи должны написать боту первыми
• Загрузка файлов ограничена 50 МБ через Bot API

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

Бот не отвечает на сообщения

• Проверьте корректность токена бота с помощью prx channel doctor telegram
• Убедитесь, что user ID или имя пользователя отправителя указаны в allowed_users
• Если allowed_users пуст, используйте /bind <code> для привязки

Ошибки ограничения частоты при потоковой передаче

• Увеличьте draft_update_interval_ms (например, до 1000 или выше)
• Telegram применяет ограничения частоты редактирования сообщений по чатам

Бот отвечает в ЛС, но не в группах

• Убедитесь, что mention_only установлен в false, или @-упоминайте бота
• В BotFather отключите режим «Group Privacy», чтобы бот мог видеть все групповые сообщения