Skip to main content
QQ integration uses the botpy SDK with WebSocket, eliminating the need for a public IP. Currently supports private messages only.

​
Features

  • ✅ WebSocket connection (no public IP required)
  • ✅ botpy SDK integration
  • ✅ Private message support
  • ✅ Open ID-based access control
  • ✅ Sandbox environment for testing

​
Prerequisites

  • QQ account registered as a developer
  • QQ mobile app for testing

​
Setup

1

Register as QQ developer

  1. Visit QQ Open Platform
  2. Click Register (注册)
  3. Choose Personal or Enterprise developer type
  4. Complete verification process
2

Create a bot application

  1. In QQ Open Platform, click Create Application (创建应用)
  2. Choose Bot (机器人) type
  3. Fill in bot name and description
  4. Submit for review
3

Get credentials

  1. Go to Developer Settings (开发设置)
  2. Copy:
    • AppID — Your application ID
    • AppSecret — Your application secret
4

Set up sandbox for testing

  1. In bot management console, find Sandbox Config (沙箱配置)
  2. Under Message List Config (在消息列表配置), click Add Member (添加成员)
  3. Add your own QQ number
  4. Once added, scan the bot’s QR code with mobile QQ
  5. Open bot profile → tap Send Message (发消息) to start chatting
5

Configure nanobot

Edit ~/.nanobot/config.json:
{
  "channels": {
    "qq": {
      "enabled": true,
      "appId": "YOUR_APP_ID",
      "secret": "YOUR_APP_SECRET",
      "allowFrom": ["YOUR_OPENID"]
    }
  }
}
6

Start the gateway

nanobot gateway
You should see:
QQ channel connected via WebSocket
7

Find your Open ID

  1. Send a message to the bot from QQ
  2. Check nanobot logs — it will display your Open ID
  3. Copy the Open ID and add it to allowFrom in config
  4. Restart gateway
Alternatively, use ["*"] to allow all users (not recommended for production).
8

Test the connection

Send a message to your bot from mobile QQ — it should respond!

​
Configuration Options

​
enabled
boolean
required
Enable the QQ channel
​
appId
string
required
App ID from QQ Open Platform
​
secret
string
required
App Secret from QQ Open Platform
​
allowFrom
array
required
List of QQ Open IDs allowed to interact with the botExamples:
  • Single user: ["11A2B3C4D5E6F7G8H9I0J"]
  • Multiple users: ["11A2B3C4D5E6F7G8H9I0J", "22K3L4M5N6O7P8Q9R0S1T"]
  • All users: ["*"] (not recommended for production)
Find Open IDs in nanobot logs when users message the bot

​
Sandbox vs Production

​
Sandbox Mode (Testing)

  • For development and testing only
  • Limited to pre-configured QQ numbers
  • Immediate access without review
  • Add members in Sandbox Config
  • Use this to test your bot before publishing

​
Production Mode (Public)

  • Available to all QQ users (after approval)
  • Requires submission and review
  • May take several days for approval
  • See QQ Bot Docs for publishing flow
To go to production:
  1. Complete bot development and testing
  2. Submit bot for review in console
  3. Wait for approval
  4. Once approved, bot is publicly available

​
Limitations

Current limitations:
  • Only private messages (DMs) are supported
  • Group chat support is not yet available
  • Some message types may have limited support

​
Troubleshooting

  1. Check sandbox config: Verify your QQ number is added to sandbox
  2. Check Open ID: Ensure your Open ID is in allowFrom
  3. Check credentials: Verify AppID and AppSecret are correct
  4. Check bot status: Ensure bot is active in QQ Open Platform
  5. Check logs: Run nanobot gateway -v for detailed logs
  1. Verify AppID and AppSecret are correct
  2. Check internet connectivity
  3. Ensure no firewall blocks WebSocket connections
  4. Try restarting gateway: nanobot gateway
  5. Check QQ Open Platform status
If you can’t find or message the bot:
  1. Verify your QQ number is added to Sandbox Config
  2. Scan the bot’s QR code with mobile QQ (not desktop)
  3. Open bot profile page
  4. Tap 发消息 (Send Message) button
  5. If still not working, wait a few minutes and try again
To get your Open ID:
  1. Temporarily set allowFrom: ["*"]
  2. Restart gateway
  3. Send a message to the bot
  4. Check logs — Open ID will be displayed
  5. Copy the Open ID and add it to allowFrom
  6. Remove "*" and restart gateway
If you see “authentication failed” errors:
  1. Go to QQ Open Platform → Your App → Developer Settings
  2. Verify AppID and AppSecret are correct
  3. If credentials changed, update config.json
  4. Restart gateway after updating

​
Complete Example

Full configuration with all options: 
{
  "channels": {
    "qq": {
      "enabled": true,
      "appId": "12345678",
      "secret": "abcdefghijklmnopqrstuvwxyz123456",
      "allowFrom": ["11A2B3C4D5E6F7G8H9I0J"]
    }
  }
}

​
Publishing to Production

Once testing is complete:
1

Submit for review

  1. Go to bot console in QQ Open Platform
  2. Click Submit for Review (提交审核)
  3. Fill in required information
  4. Upload any required materials
2

Wait for approval

  • Review typically takes 3-7 business days
  • Check review status in console
  • You may be asked for additional information
3

Go live

  1. Once approved, bot status changes to Published (已发布)
  2. Bot is now available to all QQ users
  3. Remove sandbox restrictions from config
  4. Monitor logs for production usage
For detailed publishing requirements, see QQ Bot Docs.

Configuration Overview

Learn about channel configuration

Security Settings

Set up access control

Build docs developers (and LLMs) love

Get started for freeTalk to us