{"id":8570,"library":"qq-botpy","title":"Tencent QQ Channel Python SDK","description":"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.","status":"active","version":"1.2.1","language":"en","source_language":"en","source_url":"https://github.com/tencent-connect/botpy","tags":["qq","bot","tencent","chatbot","messaging","social"],"install":[{"cmd":"pip install qq-botpy","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.7 or higher.","package":"Python","optional":false}],"imports":[{"note":"qqbot is an older, potentially unsupported library for QQ. For the official QQ Channel bot, use `qq-botpy` and import `botpy`.","wrong":"import qqbot","symbol":"Client","correct":"import botpy\nfrom botpy.types.message import Message"},{"note":"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`.","wrong":"import botpy_se","symbol":"botpy","correct":"import botpy"}],"quickstart":{"code":"import os\nimport botpy\nfrom botpy.types.message import Message\n\n# Get credentials from environment variables or provide defaults\nAPP_ID = os.environ.get(\"QQ_BOT_APP_ID\", \"YOUR_APP_ID\")\nAPP_SECRET = os.environ.get(\"QQ_BOT_APP_SECRET\", \"YOUR_APP_SECRET\")\n\nclass MyClient(botpy.Client):\n    async def on_ready(self):\n        \"\"\"Event triggered when the bot is ready.\"\"\"\n        print(f\"robot 「{self.robot.name}」 on_ready!\")\n\n    async def on_at_message_create(self, message: Message):\n        \"\"\"Event triggered when the bot receives an @ message.\"\"\"\n        # Remove the bot's mention from the message content\n        user_message_content = message.content.replace(f\"<@{self.robot.id}>\", \"\").strip()\n        \n        if user_message_content:\n            response_content = f\"Hello, {message.author.username}! You said: {user_message_content}\"\n        else:\n            response_content = f\"Hello, {message.author.username}! How can I help you?\"\n\n        await message.reply(content=response_content)\n\nif __name__ == \"__main__\":\n    # Define the intents (events the bot should listen to)\n    intents = botpy.Intents(public_guild_messages=True)\n    \n    # Create and run the client\n    client = MyClient(intents=intents)\n    client.run(appid=APP_ID, secret=APP_SECRET)","lang":"python","description":"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."},"warnings":[{"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.","message":"Authentication 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.","severity":"breaking","affected_versions":">=1.1.5"},{"fix":"Always use `pip install qq-botpy` to install the correct library. After installation, the package is imported as `import botpy`.","message":"Installing `botpy` (without `qq-`) via pip will install a completely different library for StackExchange bots, not the Tencent QQ Channel bot SDK.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your development and deployment environment uses Python 3.7 or a newer version.","message":"The minimum required Python version is 3.7+.","severity":"gotcha","affected_versions":"<3.7"},{"fix":"Before processing `message.content`, use `message.content.replace(f\"<@{self.robot.id}>\", \"\").strip()` to remove the bot's mention and leading/trailing whitespace.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"QQ 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Navigate to your bot's settings in the QQ Open Platform and enable the 'group chat' scenario. This usually requires a review period.","message":"By 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip uninstall botpy` if you installed the incorrect package, then run `pip install qq-botpy`.","cause":"You likely installed the wrong package. `pip install botpy` installs a different library.","error":"ModuleNotFoundError: No module named 'botpy'"},{"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.","cause":"Your `APP_ID` or `APP_SECRET` is incorrect or missing, or your bot's IP is not whitelisted.","error":"Failed to get access_token: {'error': {'message': 'invalid client', 'type': 'invalid_client'}}"},{"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.","cause":"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.","error":"Error code: 400 - {'error': {'message': 'invalid message content type:', 'type': 'inv.'}}"},{"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.","cause":"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.","error":"TypeError: 'NoneType' object is not subscriptable"}]}