Документация по функциям платформы QQBot
QQBotAdapter — это адаптер, построенный на основе официального протокола QQ для роботов (QQ OpenAPI), объединяющий функции для чатов в группах, личных сообщениях и каналах, предоставляющий стандартные события OneBot12, стандартные API-действия и интерфейсы для запросов.
Информация о документации
- Версия соответствующего модуля: 5.3.3
- Поддержка: ErisPulse
- Последнее обновление: 2026-11-10
Основная информация
- Краткое описание платформы: Официальный интерфейс разработки роботов QQ, поддерживающий различные сценарии, такие как групповые чаты, личные сообщения и каналы
- Название адаптера: QQBotAdapter
- Способ подключения: WebSocket-длинное соединение (по умолчанию) или Webhook HTTP-вызов обратной связи (в зависимости от настроек аккаунта, проверка подписи Ed25519)
- Способ аутентификации: appId + clientSecret для получения access_token (7200 секунд, автоматическое обновление за 45 секунд до истечения срока)
- Корневой адрес API:
https://api.bot.qq.com(с v5 официальный единый домен, sandbox устарел) - Совместимость с OneBot12: Полное покрытие отправки и получения сообщений, событий, стандартных API-действий и запросов
- Множественные аккаунты: Поддержка, произвольные аккаунты в
accountsмогут работать параллельно (возможна смешанная модель websocket/webhook)
Описание конфигурации
# config.toml
[QQBot_Adapter]
intents = "[0, 9, 12, 25, 26, 27]" # Глобальные: подписка на события intents (JSON-массив, поддержка имен событий)
[QQBot_Adapter.accounts.default]
appid = "YOUR_APPID" # ID приложения робота QQ (обязательно)
secret = "YOUR_CLIENT_SECRET" # Секретный ключ клиента робота QQ (обязательно)
mode = "websocket" # Способ получения событий: websocket / webhook
bot_id = "" # ID робота (оставьте пустым для автоматического получения; можно вручную заполнить для использования в Using())
gateway_url = "" # URL WebSocket-шлюза (оставьте пустым для получения динамически через /gateway/bot)
api_base_url = "https://api.bot.qq.com" # Корневой адрес API (можно настроить для прокси)
access_token_url = "" # Пользовательский URL для получения токена (оставьте пустым для использования официального)
webhook_path = "/webhook" # Путь обратной связи webhook (действует при mode=webhook)
enabled = true
Разрушительные изменения v5:
- Поле
sandboxустарело: официально используетсяapi.bot.qq.com, старые настройки с sandbox автоматически переносятся и игнорируются (выводится предупреждение) - Старая плоская конфигурация (appid/secret непосредственно в
[QQBot_Adapter]) автоматически переносится вaccounts.default - Рамка является мягкой зависимостью: установка адаптера не тянет версию рамки; во время выполнения проверяется наличие
ErisPulse>=2.7.1и выводится сообщение
Описание intents (поддержка позиционных номеров или имен событий):
| Позиция | Имя события | Описание |
|---|---|---|
| 0 | GUILDS | Изменения канала |
| 1 | GUILD_MEMBERS | Изменения участников канала |
| 9 | GUILD_MESSAGES | Сообщения канала (требуется проверка для частных каналов) |
| 10 | GUILD_MESSAGE_REACTIONS | Реакции на сообщения канала |
| 12 | DIRECT_MESSAGE | Личные сообщения канала |
| 24 | GROUP_MEMBER | Изменения участников группы (введено в v5) |
| 25 | GROUP_AND_C2C_EVENT | Сообщения упоминания в группе и личные сообщения |
| 26 | INTERACTION | Взаимодействие (кнопки и т.д.) |
| 27 | MESSAGE_AUDIT | События проверки сообщений |
| 28 | FORUMS_EVENT | События форума (только для частных каналов) |
| 29 | AUDIO_ACTION | Действия аудио |
| 30 | PUBLIC_GUILD_MESSAGES | Сообщения канала (общедоступные) |
# Два способа записи эквивалентны
intents = "[0, 9, 12, 25, 26, 27]"
intents = '["GUILDS", "GUILD_MESSAGES", "DIRECT_MESSAGE", "GROUP_AND_C2C_EVENT", "INTERACTION", "MESSAGE_AUDIT"]'
Стандартизация
В этом разделе описано, как адаптер соответствует стандартам ErisPulse. Подробности см. в документации SDK «Спецификация запросов» (docs/ru/standards/request-action-spec.md) и «Спецификация ответов API» (docs/ru/standards/api-response.md).
Стандартизация кодов ошибок (5.3.x)
- Единый код ошибки платформы 34100: При возврате ошибки API QQ возвращается
retcode=34100, оригинальный ответ (с кодом/сообщением QQ) сохраняется в полеqqbot_raw(ошибка при загрузке медиа также использует 34100) - Тайм-аут 33001: При таймауте API возвращается
retcode=33001(старый 32000 больше не используется) - Отсутствие контекста для удаления 10003: При отсутствии контекста для удаления сообщения в
delete_messageвозвращаетсяretcode=10003(ошибка параметра) - Резервные коды для запросов 34001/34003: При отсутствии или истечении срока запроса возвращается
34001; при отсутствии маршрута в контексте запроса возвращается34003
| retcode | Описание |
|---|---|
| 0 | Успешно |
| 10001 | Отсутствуют параметры/пустой эндпоинт |
| 10002 | Не поддерживаемое действие |
| 10003 | Невозможно определить цель отправки/аккаунт, отсутствие контекста для удаления и т.д. ошибка параметра |
| 33000 | Сетевая/ошибка вызова API |
| 33001 | Тайм-аут запроса |
| 34001 | Запрос отсутствует или истек (Request DSL) |
| 34003 | В контексте запроса отсутствует маршрутный параметр (Request DSL) |
| 34100 | Ошибка бизнес-логики платформы (оригинальный ответ и код QQ сохраняются в qqbot_raw) |
Стандартизация имен уведомлений (5.3.x)
События добавления/удаления друзей унифицированы:
| Оригинальное событие | Преобразованное detail_type | Описание |
|---|---|---|
| FRIEND_ADD | friend_increase |
Добавление друга (старое friend_add устарело) |
| FRIEND_DEL | friend_decrease |
Удаление друга (старое friend_del устарело) |
Сохранение контекста запроса (начиная с 5.3.2)
Входящие события запроса на вступление в группу будут сопоставлять request_id с контекстом запроса (группа/открытый идентификатор участника) и кэшировать (TTL 3600 секунд, максимальное количество 512 записей, очистка после успешной обработки), при выполнении одобрения маршрутизация к POST /v2/groups/{group_openid}/approval_join_request/{member_openid}.
Маршрутизация расширенных действий (5.3.x)
Проверка прав участника канала предоставляется через расширенные действия с префиксом платформы:
result = await qqbot.Api.call("qqbot.get_channel_member_permissions", channel_id="...", member_id="...")
send_context для потоковой отправки
Потоковые сообщения (.Stream()) используют send_context: в цепочке событий автоматически используется текущий аккаунт источника, явно указанный аккаунт в Using() имеет приоритет.
Отправка сообщений
Базовая отправка
from ErisPulse import sdk
qqbot = sdk.adapter.get("qqbot")
# Отправка текста
await qqbot.Send.To("user", user_openid).Text("Hello World!")
# Упоминание в группе (автоматически использует формат <qqbot-at-user id="x" />)
await qqbot.Send.To("group", group_openid).At("member_openid").Text("@you")
await qqbot.Send.To("group", group_openid).AtAll().Text("Анонс")
# Сообщение в канале (упоминание автоматически использует формат <@user_id>)
await qqbot.Send.To("channel", channel_id).Text("Сообщение канала")
# Личное сообщение в канале (сначала создайте сессию)
dms = await qqbot.create_dms(user_id, source_guild_id)
await qqbot.Send.To("dms", dms["data"]["guild_id"]).Text("Личное сообщение")
# Ответ на сообщение (ответное сообщение, автоматически включает msg_id)
await qqbot.Send.To("group", group_openid).Reply(msg_id).Text("Содержание ответа")
# Множественные аккаунты (указание имени аккаунта или bot_id в Using/Account)
await qqbot.Send.Using("account2").To("group", group_openid).Text("От второго робота")
Мультимедиа
# Поддержка URL / локального пути / бинарных данных; при превышении 5 МБ автоматически разбивается на части
await qqbot.Send.To("group", gid).Image("https://example.com/img.png")
await qqbot.Send.To("user", uid).Image("/path/to/local.png")
await qqbot.Send.To("user", uid).Voice(open("audio.mp3", "rb").read())
await qqbot.Send.To("user", uid).Video("https://example.com/v.mp4")
await qqbot.Send.To("user", uid).File(b"...", filename="doc.pdf")
# Изображения каналов отправляются напрямую через multipart (file_image)
await qqbot.Send.To("channel", cid).Image(open("img.png", "rb").read())
file_type отображается: изображение=1, видео=2, аудио=3, файл=4 (по типу сообщения автоматически определяется, file по расширению файла)
Markdown / Ark / Embed / Keyboard
# Оригинальный Markdown
await qqbot.Send.To("group", gid).Markdown("# Заголовок\n- Элемент списка")
# Markdown с шаблоном
await qqbot.Send.To("user", uid).Markdown(template_id=1, kv=[{"key": "title", "value": "Уведомление"}])
await qqbot.Send.To("user", uid).Markdown(custom_template_id="23456", kv=[...])
# Ark-шаблон
await qqbot.Send.To("user", uid).Ark(23, [{"key": "a", "value": "b"}])
# Embed (только для каналов/личных сообщений)
await qqbot.Send.To("channel", cid).Embed({"title": "Заголовок", "content": "Содержание"})
# Клавиатура (автоматически устанавливается тип markdown и добавляется bot_appid)
keyboard = {"content": {"rows": [[{"label": "Подтвердить", "type": 2, "data": "ok"}]]}}
await qqbot.Send.To("group", gid).Keyboard(keyboard).Text("Выберите")
# Объединение пересылки (официальный md не поддерживает складной синтаксис, отображается как список цитат; требует разрешения на оригинальный Markdown, в случае неудачи автоматически возвращается текст)
await qqbot.Send.To("group", gid).MergeForward(nodes)
Потоковая отправка (ново в v5, личные сообщения)
# Однократная потоковая отправка (input_state=10 завершает сразу)
await qqbot.Send.To("user", openid).Stream("Содержание ответа")
# Многократная потоковая отправка
r = await qqbot.stream_message(openid, "Первая часть", input_state=1, msg_id=активный_msg_id)
stream_id = r["data"]["id"]
r = await qqbot.stream_message(openid, "Вторая часть", stream_msg_id=stream_id, index=1, input_state=1)
r = await qqbot.stream_message(openid, "Последняя часть", stream_msg_id=stream_id, index=2, input_state=10)
Отмена сообщения
# Стандартное API-действие: автоматически маршрутизируется по источнику сообщения (группа/личное сообщение/канал/личное) к соответствующему конечному пункту отмены
await qqbot.Api.delete_message(message_id)
Адаптер автоматически регистрирует отправку и получение сообщений, не требуя ручного передачи group_id/channel_id; при отсутствии контекста возвращается retcode=10003.
Стандартные API-действия OneBot12 (ново в v5)
# Информация о роботе
result = await qqbot.Api.get_self_info()
# Управление группой
result = await qqbot.Api.get_group_info(group_openid) # {group_id, group_name}
result = await qqbot.Api.get_group_member_list(group_openid) # автоматическая пагинация и объединение
result = await qqbot.Api.get_group_member_info(group_openid, member_openid)
# Канал
result = await qqbot.Api.get_guild_list()
result = await qqbot.Api.get_guild_info(guild_id)
result = await qqbot.Api.get_guild_member_list(guild_id)
result = await qqbot.Api.get_channel_list(guild_id)
result = await qqbot.Api.get_channel_info(guild_id, channel_id)
await qqbot.Api.set_channel_name(guild_id, channel_id, "Новое название")
await qqbot.Api.leave_channel(guild_id, channel_id) # удаление подканала
# Основные действия
result = await qqbot.Api.get_status() # {"good": bool, "bots": [...]}
result = await qqbot.Api.get_version() # {"impl": "ErisPulse-QQBotAdapter", "onebot_version": "12"}
# Множественные аккаунты
result = await qqbot.Api.Using("account2").get_self_info()
Поддерживаемые стандартные действия: get_self_info / get_group_info / get_group_member_info / get_group_member_list / get_guild_info / get_guild_list / get_guild_member_info / get_guild_member_list / get_channel_info / get_channel_list / set_channel_name / leave_channel / delete_message / get_status / get_version / get_supported_actions. Действия, которые не поддерживаются, возвращают retcode=10002 (например, get_friend_list, так как у QQ нет соответствующего API).
Запросы и операции (Request DSL, ново в v5)
Событие GROUP_JOIN_REQUEST (запрос на вступление в группу) преобразуется в событие request однозначного взаимодействия, поддерживающее стандартизированное одобрение:
from ErisPulse.Core.Event import request as request_event
@request_event.on_request()
async def handle_join_request(event):
if event.get("platform") != "qqbot":
return
# автоматическое одобрение
result = await event.approve()
# или отклонение: await event.reject(comment="не соответствует условиям")
# или указание аккаунта: await qqbot.Request(event["request_id"]).Using("account2").accept()
request_id= официальныйjoin_request_id- адаптер автоматически кэширует контекст запроса (группа/открытый идентификатор участника), при выполнении маршрутизируется к
POST /v2/groups/{group_openid}/approval_join_request/{member_openid} - отклонение может сопровождаться
reject_reason; при истечении срока контекста возвращаетсяretcode=34001
Также можно напрямую вызывать методы платформы:
await qqbot.approve_group_join(group_openid, member_openid, join_request_id, approve=True)
await qqbot.approve_group_join(group_openid, member_openid, approve=False, reject_reason="причина")
Пользовательские методы API платформы
Адаптер предоставляет полный набор API QQ (первый параметр — ID цели, account_id — необязательный, для указания аккаунта):
Робот / Взаимодействие
get_me()、reply_interaction(interaction_id, code=0)
Канал (Guild)
get_guilds()、get_guild(guild_id)、mute_guild_all(guild_id, mute_seconds)、
get_guild_roles / create_guild_role / update_guild_role / delete_guild_role、
get_guild_api_permission、demand_guild_api_permission(guild_id, channel_id, path, method, desc)
Подканал (Channel)
get_channels、get_channel、create_channel(guild_id, name, type=0, ...)、update_channel(channel_id, name=..., ...)、delete_channel、
get_channel_pins、pin_message、unpin_message
Участники канала
get_guild_members、get_guild_member、mute_guild_members (массово/всей группе), mute_guild_member、
add_guild_member_role / remove_guild_member_role、kick_guild_member
Разрешения / Объявления / Реакции
get_channel_role_permissions、update_channel_role_permissions、get_channel_member_permissions (расширенное действие qqbot.get_channel_member_permissions)、update_channel_member_permissions、create_announce、
add_reaction、delete_reaction、get_reaction_users
Расписания / Темы / Аудио
get_schedules、get_schedule、create_schedule、update_schedule、delete_schedule、
get_threads、get_thread、publish_thread(channel_id, title, content, format=3)、delete_thread、
control_audio(channel_id, audio_url, text, status)、mic_online、mic_offline
Управление группами (v2, некоторые интерфейсы доступны только для роботов в белом списке)
await qqbot.get_group_info_raw(group_openid) # Информация о группе
await qqbot.get_group_bot_state(group_openid) # Состояние робота в группе
await qqbot.get_group_members(group_openid) # Список участников (с next_cursor)
await qqbot.get_group_member(group_openid, member_openid)
await qqbot.batch_remove_group_members(group_openid, [member_openid], add_to_blacklist=False)
await qqbot.get_group_member_blacklist(group_openid)
await qqbot.update_group_member_blacklist(group_openid, "add", [member_openid])
await qqbot.get_group_join_requests(group_openid) # Список запросов на вступление в группу
await qqbot.approve_group_join(...) # Одобрение запроса на вступление
await qqbot.get_group_restrict_setting(group_openid) # Настройки запрета
await qqbot.set_group_restrict(group_openid, [{"op": "add", "member_openid": "...", "mute_expire_at": 123}])
# Стратегии одобрения вступления
await qqbot.get_join_approval_strategies()
await qqbot.create_join_approval_strategy(strategy_dict)
await qqbot.update_join_approval_strategy(strategy_id, **fields)
await qqbot.delete_join_approval_strategy(strategy_id)
await qqbot.execute_join_approval_strategy(strategy_id)
await qqbot.update_join_approval_strategy_whitelist(strategy_id, "add", [user_ids])
Пользовательские меню / Панели команд (ново в v5)
# Глобальное пользовательское меню (действует только для C2C; подменю максимум 5, не вложенные)
menu_items = [
{"type": "send_message", "content": {"label": "Помощь", "content": "/help"}},
{"type": "link", "content": {"label": "Официальный сайт", "content": "https://example.com"}},
]
await qqbot.update_custom_menu(menu_items)
result = await qqbot.get_custom_menu()
# Панель команд (scope: c2c/group/channel/dm; максимум 20 на робота)
await qqbot.create_command_panel("c2c", [
{"type": "command", "content": {"label": "Погода", "content": "/weather"}},
{"type": "link", "content": {"label": "Больше", "content": "https://example.com"}},
], remark="Заметка панели", target_type="all")
await qqbot.get_command_panels("c2c")
await qqbot.get_command_panel(panel_id)
await qqbot.update_command_panel(panel_id, items)
await qqbot.delete_command_panel(panel_id)
await qqbot.update_command_panel_targets(panel_id, "add", user_openids=[...])
WebSocket-соединение
Процесс подключения
- appId + clientSecret получают access_token (POST https://bots.qq.com/app/getAppAccessToken)
- Через GET /gateway/bot получают адрес шлюза (при настройке gateway_url используется напрямую)
- Получают OP_HELLO (op=10), получают интервал心跳
- Отправляют OP_IDENTIFY (op=2) для аутентификации (intents поддерживает комбинацию битовых операций)
- Получают READY, получают session_id и bot_id, отправляют событие connect meta
- Цикл心跳 (op=1) и распределение событий (op=0)
Переподключение при разрыве
- Максимум 50 попыток переподключения, экспоненциальная задержка
min(5 * 2^n, 300)секунд - Получение OP_RECONNECT (op=7) сохраняет сессию (Resume); OP_INVALID_SESSION (op=9) переподключается с идентификацией
- При нормальной отправке и получении автоматически сбрасывается счетчик переподключения
Управление токеном
- access_token действителен 7200 секунд, автоматически обновляется за 45 секунд до истечения срока (ленивая проверка при запросе)
- При неудачном обновлении автоматически повторяется 3 раза (возрастающая задержка)
- Заголовки запроса:
Authorization: QQBot {token}+X-Union-Appid: {appid}(ново в v5)
Webhook-подключение (ново в v5)
Установка mode аккаунта в webhook позволяет использовать HTTP-вызов обратной связи для получения событий:
[QQBot_Adapter.accounts.mybot]
appid = "..."
secret = "..."
mode = "webhook"
webhook_path = "/webhook" # При наличии нескольких webhook аккаунтов автоматически добавляется имя аккаунта для избежания конфликтов
- Адаптер регистрирует HTTP-маршруты через ErisPulse router, в логах запуска выводится полный URL обратной связи
- Проверка подписи Ed25519: seed = secret циклически заполняется до 32 байт; проверка подписи
X-Signature-Ed25519дляX-Signature-Timestamp + body - Автоматически обрабатывает op=13 проверку подписи handshake (валидация URL обратной связи) и op=0 распределение событий
- Зависит от библиотеки
cryptography(установлена вместе с адаптером)
Подписка на события и система openid
- QQBot использует систему openid вместо QQ-номеров, идентификаторы пользователей/групп являются строками openid
- Групповые сообщения по умолчанию получают только при упоминании робота (событие
GROUP_AT_MESSAGE_CREATE) - Получение всех групповых сообщений: необходимо включить соответствующие разрешения в QQ Open Platform на панели управления роботом (без API можно настроить); после включения неупомянутые групповые сообщения будут поступать через
GROUP_MESSAGE_CREATE, адаптер полностью поддерживает преобразование (отмечаетсяqqbot_is_at_message=false; если сообщение содержит упоминание робота, автоматически распознается как упоминание) - Упоминание: Упоминание в QQ содержится в имени события, и упоминание в групповом сообщении имеет формат
<@{group_openid}>(отличается от bot_id в READY). Адаптер автоматически анализирует оба стиля упоминания и вставляет/нормализует упоминание робота, обеспечивая доступностьon_at_message()/is_at_message(). Также автоматически изучает openid робота в каждой группе, обеспечивая распознавание упоминаний вGROUP_MESSAGE_CREATEпри режиме получения всех групповых сообщений (оригинальный openid сохраняется в упоминанииdata.qqbot_openid) - Ответное сообщение: для групповых/личных сообщений необходимо включать
msg_idилиevent_id, адаптер автоматически кэширует и добавляет event_idне может использоваться вместе с мультимедиа (ограничение официального API), адаптер автоматически обрабатывает понижение уровня- Отправка может вызвать проверку, результат уведомляется через события
qqbot_audit_pass/qqbot_audit_reject - При выходе программы вызовите
shutdown()для освобождения ресурсов
Примеры использования
Обработка групповых сообщений (детектирование упоминания)
from ErisPulse.Core.Event import message
@message.on_at_message()
async def handle_at(event):
if event.get("platform") != "qqbot":
return
text = event.get_text()
if text == "签到":
await event.reply("已签到")
Обработка кнопочных взаимодействий
from ErisPulse.Core.Event import notice
@notice.on_notice()
async def handle_interaction(event):
if event.get("detail_type") != "qqbot_interaction":
return
button_id = event.get("qqbot_button_id")
await qqbot.reply_interaction(event.get("qqbot_interaction_id"), code=0)
if button_id == "confirm":
await qqbot.Send.To("group", event.get("group_id")).Text("已确认")
Запуск множественных аккаунтов
[QQBot_Adapter.accounts.bot_a]
appid = "A_APPID"
secret = "..."
enabled = true
[QQBot_Adapter.accounts.bot_b]
appid = "B_APPID"
secret = "..."
mode = "webhook"
enabled = true
Два аккаунта запускаются параллельно: bot_a использует WebSocket, bot_b использует Webhook, они не влияют друг на друга.