QQBot Messaging Framework

What Problem It Solves

Building a QQ bot often gets stuck less on raw API calls and more on the differences between guild @-mentions, C2C private messages, and group @-mentions. Each path has its own Intent, event handler, message type, reply method, and user identifier. For example, guild messages require public_guild_messages=True, while C2C and group messages share public_messages=True but still use different send methods and ID fields. Adding scheduled pushes makes the failure surface larger: asyncio task setup, event-loop initialization, and short-lived msg_id values can all break the message flow.

How The Skill Works

The skill organizes qq-botpy into a practical messaging pattern for three core cases:

• Guild @-messages: handle on_at_message_create(message: Message), reply with message.reply(content="..."), and send proactively with self.api.post_message(channel_id=..., content=..., msg_id=message.id). The user identifier is message.author.id.
• C2C private messages: handle on_c2c_message_create(message: C2CMessage), reply with message._api.post_c2c_message(openid=..., msg_type=0, msg_id=message.id, content=...), and use message.author.user_openid for the recipient.
• Group @-messages: handle on_group_at_message_create(message: GroupMessage), reply with message._api.post_group_message(group_openid=..., msg_type=0, msg_id=message.id, content=...), and use message.author.member_openid plus message.group_openid.

It also includes a scheduled-push pattern using asyncio.create_task(), await asyncio.sleep(seconds), and try/except asyncio.CancelledError so background jobs can exit cleanly. For command-style messages, prefix parsing needs to happen before argument extraction.

Boundaries And Caveats

• Intents are mandatory: missing public_guild_messages=True or public_messages=True means messages will not arrive.
• Reply IDs expire: passive replies rely on a recent msg_id; scheduled sends may need proactive-message permissions or a fresh msg_id from a newer incoming message.
• Event loops matter on Python 3.10+: if you see RuntimeError: There is no current event loop, explicitly create and set the loop before starting the bot.