Registry / communication / qq-botpy

qq-botpy

JSON →
library1.2.1pypypi✓ verified 89d ago

qq-botpy is the official Python SDK for creating bots on Tencent's QQ Channels, providing an easy-to-use and efficient framework for developers. It abstracts the complexities of the QQ Open Platform API, enabling quick development of features like message handling and event listening. The library is actively maintained, with frequent updates; the current stable version is 1.2.1.

pip install qq-botpy
INSTALL
IMPORT
SIG · QQ-BOTPY
Q
qq-botpy
communicationpythonv1.2.1
Install
4.2s avg
Import
785ms
Disk
31MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v1.2.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.823s · 30.8MB
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 4.2s · import 0.747s · 34MB
31MB installed
● package 31MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client
✓ import botpy from botpy.types.message import Message
✗ import qqbot
qqbot is an older, potentially unsupported library for QQ. For the official QQ Channel bot, use `qq-botpy` and import `botpy`.
botpy
✓ import botpy
✗ import botpy_se
A common footgun is installing `botpy` (which is a different library for StackExchange bots) instead of `qq-botpy` for Tencent QQ bots. Ensure you `pip install qq-botpy` then `import botpy`.

This quickstart demonstrates how to create a basic QQ Channel bot that responds to @-mentions. It requires your QQ bot's AppID and AppSecret, which should be set as environment variables `QQ_BOT_APP_ID` and `QQ_BOT_APP_SECRET` for security, or replaced directly with your credentials. The bot will print a 'ready' message and reply to any public guild message where it is @-mentioned.

import os import botpy from botpy.types.message import Message # Get credentials from environment variables or provide defaults APP_ID = os.environ.get("QQ_BOT_APP_ID", "YOUR_APP_ID") APP_SECRET = os.environ.get("QQ_BOT_APP_SECRET", "YOUR_APP_SECRET") class MyClient(botpy.Client): async def on_ready(self): """Event triggered when the bot is ready.""" print(f"robot 「{self.robot.name}」 on_ready!") async def on_at_message_create(self, message: Message): """Event triggered when the bot receives an @ message.""" # Remove the bot's mention from the message content user_message_content = message.content.replace(f"<@{self.robot.id}>", "").strip() if user_message_content: response_content = f"Hello, {message.author.username}! You said: {user_message_content}" else: response_content = f"Hello, {message.author.username}! How can I help you?" await message.reply(content=response_content) if __name__ == "__main__": # Define the intents (events the bot should listen to) intents = botpy.Intents(public_guild_messages=True) # Create and run the client client = MyClient(intents=intents) client.run(appid=APP_ID, secret=APP_SECRET)
Debug
Known issues
breakingAuthentication method changed from a single 'token' to 'AppID + AppSecret' in v1.1.5. Older versions using a token will cease to function with new API requirements.
fix
Update your bot configuration to use `client.run(appid='YOUR_APP_ID', secret='YOUR_APP_SECRET')` instead of `client.run(token='YOUR_TOKEN')`. Obtain your AppSecret from the QQ bot development settings page.
affects: >=1.1.5
gotchaInstalling `botpy` (without `qq-`) via pip will install a completely different library for StackExchange bots, not the Tencent QQ Channel bot SDK.
fix
Always use `pip install qq-botpy` to install the correct library. After installation, the package is imported as `import botpy`.
affects: All versions
gotchaThe minimum required Python version is 3.7+.
fix
Ensure your development and deployment environment uses Python 3.7 or a newer version.
affects: <3.7
gotchaWhen replying to an `@` message, `message.content` will include the bot's `@username` prefix (e.g., `@bot_name your message`). This prefix needs to be stripped if you want to process only the user's actual message.
fix
Before processing `message.content`, use `message.content.replace(f"<@{self.robot.id}>", "").strip()` to remove the bot's mention and leading/trailing whitespace.
affects: All versions
gotchaQQ bots have rate limits for sending messages. For personal developers, this can be as low as 5 passive replies per minute. Exceeding this limit can result in messages being silently dropped without error.
fix
Implement rate limiting or a cooldown mechanism in your bot logic, especially for high-frequency interactions or large groups. Consider truncating long replies if they might hit character limits.
affects: All versions
gotchaBy default, personal developer QQ bots only have channel permissions. To enable group chat functionality, you must explicitly apply for and enable 'group chat' scenarios in the QQ Open Platform backend.
fix
Navigate to your bot's settings in the QQ Open Platform and enable the 'group chat' scenario. This usually requires a review period.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'botpy'
You likely installed the wrong package. `pip install botpy` installs a different library.
fix
Run `pip uninstall botpy` if you installed the incorrect package, then run `pip install qq-botpy`.
Failed to get access_token: {'error': {'message': 'invalid client', 'type': 'invalid_client'}}
Your `APP_ID` or `APP_SECRET` is incorrect or missing, or your bot's IP is not whitelisted.
fix
Double-check your `APP_ID` and `APP_SECRET` from the QQ Open Platform. Ensure they are correctly passed to `client.run()`. Verify that your server's IP address is whitelisted in the QQ Open Platform settings if applicable.
Error code: 400 - {'error': {'message': 'invalid message content type:', 'type': 'inv.'}}
The message content or type being sent is not valid according to the QQ API, or it might be a rate limit issue leading to malformed requests.
fix
Review the content you are attempting to send. Ensure it adheres to QQ API message format requirements. If sending rich media, ensure the payload is correct. Check for rate limits, as frequent requests can sometimes lead to such errors.
TypeError: 'NoneType' object is not subscriptable
This error often occurs during client startup if `client._ws_ap` is `None` because `self.api.get_ws_url()` timed out or failed to return valid session metadata.
fix
This can indicate network issues or a transient API problem with the QQ backend. Check your network connection and ensure your bot's server can reach the QQ API. Consider adding retry logic or increasing the client's timeout setting if available.
Upgrade
Version history
1.2.1latest on PyPI · released Mar 22, 2024
Audit
Dependencies
PythonrequiredRequires Python 3.7 or higher.
Agent activity
26 hits · last 30 days
node
22
OpenAI (training)
1
Resources
qq-botpy — pip install qq-botpy · libregistry