QQ Channel Integration

​

Prerequisites

• QQ Bot Platform access
• QQ developer account
• App ID and App Secret

​

Creating a QQ Bot

1. Register for QQ Bot Platform
   • Visit QQ Open Platform
   • Log in with your QQ account
   • Apply for bot development access
2. Create Bot Application
   • Go to Bot Management Console
   • Click “Create Bot”
   • Fill in bot information:
     • Bot Name
     • Bot Description
     • Bot Avatar
   • Submit for review
3. Get Credentials
   • After approval, go to bot settings
   • Note your App ID (numeric)
   • Generate and save App Secret
4. Configure Bot Permissions
   • Enable required permissions:
     • ✅ C2C Messages (Direct messages)
     • ✅ Group AT Messages (Group mentions)
   • Set bot visibility (public/private)

​

Configuration

channels:
  qq:
    enabled: true
    app_id: "YOUR_APP_ID"
    app_secret: "YOUR_APP_SECRET"
    allow_from:
      - "12345678"  # QQ user IDs

​

Configuration Options

​

User ID Format

1. User’s QQ number is their user ID
2. Check Weaver logs after receiving a message:
   Received C2C message sender=12345678
   

​

Supported Features

​

Message Types

• Text messages (C2C and Group AT)
• Direct messages (C2C)
• Group mentions (requires @bot)

• Rich media (images, voice, files)
• Markdown formatting
• Embeds and cards

​

Message Handling

• Bot responds to all direct messages
• No mention required
• Uses user ID as chat ID

• Bot only responds when @mentioned
• Mention is required in group chats
• Prevents spam in busy groups

​

Connection Mode

• Protocol: QQ Bot Gateway (WebSocket)
• Authentication: OAuth 2.0 with automatic token refresh
• Reconnection: Automatic on disconnect
• Sharding: Supported for high-traffic bots

​

Token Management

• Access tokens auto-refresh before expiration
• Token source maintains valid credentials
• No manual token management needed

​

Bot Behavior

​

Direct Messages

User → Bot (Direct): "Hello"
Bot receives: "Hello"
Bot responds to: User's QQ ID

​

Group Messages

User in Group: "@BotName what's the weather?"
Bot receives: "@BotName what's the weather?"
Bot responds to: Group ID

​

Message Deduplication

• Tracks processed message IDs
• Prevents duplicate processing
• Automatic cleanup (maintains 10,000 recent IDs)
• Thread-safe implementation

​

Error Handling

​

Common Issues

QQ app_id and app_secret not configured

• Verify App ID and App Secret in config
• Ensure credentials are from Bot Management Console

failed to start token refresh: ...

• Check App Secret is correct
• Verify bot is not suspended/deleted
• Ensure network connectivity to QQ API

WebSocket session error

• Check network connectivity
• Verify firewall allows outbound WebSocket
• Bot may be rate-limited (check QQ console)

Message rejected by allowlist user_id: 12345678

• Add user ID to allow_from list
• Or remove allow_from to allow all users

Received message with no sender ID

• Message format issue (should not occur normally)
• Check QQ API changes or updates

​

Security Considerations

1. Credential Security: Keep App ID and App Secret secure
2. Token Storage: Tokens stored in memory only (not persisted)
3. Allowlist: Use allow_from to restrict bot access
4. Rate Limiting: QQ enforces API rate limits
5. Message Validation: All messages validated before processing

​

Metadata Captured

metadata:
  message_id: "123456789012345678"

metadata:
  message_id: "123456789012345678"
  group_id: "987654321"

​

Example Configurations

​

Basic Setup

channels:
  qq:
    enabled: true
    app_id: "123456789"
    app_secret: "abcdef1234567890abcdef1234567890"

​

With Allowlist

channels:
  qq:
    enabled: true
    app_id: "123456789"
    app_secret: "abcdef1234567890abcdef1234567890"
    allow_from:
      - "12345678"   # alice
      - "87654321"   # bob
      - "11111111"   # charlie

​

Logging

# View QQ-specific logs
grep "qq" weaver.log

# Monitor connections
tail -f weaver.log | grep qq

Starting QQ bot (WebSocket mode)
Got WebSocket info shards=1
QQ bot started successfully
Received C2C message sender=12345678 length=13
Received group AT message sender=87654321 group=123456789 length=25

​

API Version

• Library: github.com/tencent-connect/botgo
• Protocol: QQ Bot Gateway (WebSocket)
• Authentication: OAuth 2.0
• API Version: Latest stable

​

Limitations

​

Current Limitations

1. Text Only: Only text messages currently supported
2. No Media: Image/voice/file support planned for future
3. Group AT Only: Groups require @mention (by design)
4. No Formatting: Plain text output only

​

QQ Platform Limits

• Rate Limits: Enforced by QQ (varies by bot type)
• Message Length: Limited by QQ API
• Bot Review: Bots must be approved by QQ
• Regional: Primarily for China region

​

Bot Approval Process

1. Submit Bot: Create bot in console
2. Provide Info: Name, description, use case
3. Wait for Review: 1-7 days typical
4. Get Approved: Receive credentials
5. Test: Use sandbox environment first
6. Go Live: Deploy production bot

​

Best Practices

1. Test Credentials: Verify App ID/Secret before deployment
2. Monitor Logs: Watch for authentication errors
3. Handle Dedup: Bot automatically deduplicates messages
4. Respond Quickly: QQ users expect fast responses
5. Use Allowlist: Limit access during testing
6. Check Shards: Monitor shard count for large bots

​

Troubleshooting

​

Bot Not Receiving Messages

1. Check bot is started: QQ bot started successfully
2. Verify WebSocket connected
3. Ensure permissions enabled in QQ console
4. Try sending direct message (C2C) first
5. For groups, verify bot is @mentioned

​

Bot Not Sending Messages

1. Check QQ bot not running error
2. Verify access token is valid
3. Check rate limiting in logs
4. Ensure chat ID format is correct

​

Future Enhancements

• Rich media support (images, voice, files)
• Markdown/HTML formatting
• Interactive buttons and cards
• Voice message transcription
• Improved group message handling

​

Next Steps

• Configure Agents to respond on QQ
• Set up Message Routing for multi-channel support
• Enable Logging for debugging