QQ

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

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

• Аккаунт QQ (личный или корпоративный)
• Бот-приложение, зарегистрированное на QQ Open Platform
• App ID и App Secret из консоли разработчика
• Бот должен быть одобрен и опубликован (для тестирования доступен sandbox-режим)

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

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

1. Перейдите на QQ Open Platform и войдите с вашим аккаунтом QQ
2. Перейдите в «Приложения» и создайте новое бот-приложение
3. Заполните имя бота, описание и аватар
4. В разделе «Настройки разработки» скопируйте App ID и App Secret
5. Настройте намерения (intents) бота — типы событий, которые бот должен получать
6. Для тестирования включите sandbox-режим, который ограничивает бота выделенной тестовой гильдией

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

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

[channels_config.qq]
app_id = "102012345"
app_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
allowed_users = ["user_openid_1", "user_openid_2"]
sandbox = true

Установите sandbox = false после одобрения бота для продакшен-использования.

3. Проверка

prx channel doctor qq

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

Поле	Тип	По умолчанию	Описание
app_id	String	обязательный	ID приложения из консоли разработчика QQ Open Platform
app_secret	String	обязательный	Секрет приложения из консоли разработчика
allowed_users	[String]	[]	Разрешённые OpenID пользователей. Пусто = режим сопряжения. "*" = разрешить всем
sandbox	bool	false	При true подключение к sandbox-шлюзу для тестирования
intents	[String]	["guilds", "guild_messages", "direct_messages"]	Намерения событий для подписки
stream_mode	String	"none"	Режим стриминга: "none" или "typing". В режиме typing отправляется индикатор набора текста во время генерации
interrupt_on_new_message	bool	false	При true новое сообщение от того же отправителя отменяет текущий запрос
mention_only	bool	false	При true отвечать только на @-упоминания в группах или каналах гильдий. ЛС обрабатываются всегда
ack_reactions	bool	наследуется	Переопределение глобальной настройки ack_reactions. Если не задано, используется [channels_config].ack_reactions

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

PRX подключается к QQ Bot API через событийный поток на основе WebSocket. Жизненный цикл подключения:

1. Аутентификация — PRX получает токен доступа, используя App ID и App Secret через OAuth2 client credentials
2. Обнаружение шлюза — бот запрашивает URL WebSocket-шлюза из QQ API
3. Установка сессии — открывается WebSocket-соединение к шлюзу с токеном доступа
4. Подписка на намерения — бот объявляет, какие типы событий он хочет получать
5. Цикл событий — входящие сообщения передаются в цикл агента PRX; ответы отправляются через REST API

QQ Gateway (WSS) ──► PRX Channel Handler ──► Agent Loop
                                                │
QQ REST API ◄───── Reply with message ◄────────┘

Возможности

• Сообщения в гильдиях и группах — ответы на сообщения в гильдиях (каналах) QQ и групповых чатах
• Личные сообщения — обработка приватных разговоров 1:1 с пользователями
• Режим сопряжения — безопасная одноразовая привязка кодом, когда разрешённые пользователи не настроены
• Медиавложения — поддержка отправки и получения изображений, файлов и карточек с мультимедиа
• Ответы в Markdown — боты QQ поддерживают подмножество форматирования Markdown в ответах
• Реакции подтверждения — реакции на входящие сообщения для подтверждения получения (при включении)
• Sandbox-режим — тестирование бота в изолированном окружении гильдии перед продакшен-развёртыванием
• Автоматическое обновление токена — токены доступа автоматически обновляются до истечения срока действия
• Кросс-платформенность — работает в QQ для десктопа, мобильных устройств и QQ для Linux

Типы сообщений

QQ Bot API поддерживает несколько типов содержимого сообщений:

Тип	Направление	Описание
Текст	Отправка / Получение	Текстовые сообщения, до 2048 символов
Markdown	Отправка	Форматированный текст с подмножеством Markdown QQ
Изображение	Отправка / Получение	Вложения изображений (JPEG, PNG, GIF)
Файл	Получение	Файловые вложения от пользователей
Мультимедийная карточка	Отправка	Структурированные карточки с заголовком, описанием и миниатюрой
Ark-шаблон	Отправка	Мультимедийные сообщения на основе шаблонов системы Ark QQ

Намерения (Intents)

Намерения управляют тем, какие события получает бот. Доступные намерения:

Намерение	События	Примечания
guilds	Создание, обновление, удаление гильдии	Изменения метаданных гильдии
guild_members	Добавление, обновление, удаление участника	Требуются повышенные разрешения
guild_messages	Сообщения в текстовых каналах гильдий	Наиболее распространённое намерение
guild_message_reactions	Добавление/удаление реакций в гильдиях	Эмодзи-реакции
direct_messages	Приватные ЛС с ботом	Всегда рекомендуется
group_and_c2c	Групповые чаты и C2C-сообщения	Требуется отдельное одобрение
interaction	Нажатия кнопок и взаимодействия	Для интерактивных компонентов сообщений

Ограничения

• QQ Bot API имеет региональные ограничения; боты доступны преимущественно в материковом Китае
• Sandbox-режим ограничивает бота одной тестовой гильдией с небольшим количеством участников
• Продакшен-боты требуют одобрения от команды проверки QQ Open Platform
• Групповые чаты и C2C-сообщения требуют отдельной заявки на разрешение
• Загрузка файлов ограничена 20 МБ на вложение
• Модерация контента применяется QQ; сообщения с запрещённым содержимым отклоняются без уведомления
• Действуют лимиты частоты запросов: примерно 5 сообщений в секунду на гильдию, 2 в секунду для ЛС
• Бот не может инициировать разговоры; пользователи или администраторы должны сначала добавить бота

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

Бот не подключается к шлюзу QQ

• Проверьте корректность app_id и app_secret с помощью prx channel doctor qq
• При использовании sandbox-режима убедитесь, что установлено sandbox = true (sandbox и продакшен используют разные шлюзы)
• Проверьте, что исходящие подключения к api.sgroup.qq.com и WebSocket-шлюзу не блокируются

Бот подключается, но не получает сообщения

• Проверьте, что в конфигурации указаны корректные intents для вашего сценария использования
• В каналах гильдий боту может потребоваться разрешение «Получение сообщений» от администратора гильдии
• Убедитесь, что OpenID отправителя указан в allowed_users, или установите allowed_users = ["*"]

Ответы не доставляются

• QQ применяет модерацию контента; проверьте логи PRX на наличие ответов об отклонении от API
• Убедитесь, что бот имеет разрешение «Отправка сообщений» в целевой гильдии или группе
• Для ответов в ЛС пользователь должен сначала написать боту для открытия разговора

Ошибки обновления токена

• Секрет приложения мог быть ротирован в консоли разработчика; обновите конфигурацию новым секретом
• Сетевые проблемы могут препятствовать обновлению токена; проверьте подключение к bots.qq.com

Связанные страницы

• Обзор каналов
• DingTalk — аналогичная настройка для платформы DingTalk
• Lark — аналогичная настройка для Lark / Feishu
• Безопасность: Сопряжение — подробности о сопряжении через одноразовый код привязки