QQ Bot

​

Overview

• Receive messages via a persistent WebSocket connection to the QQ Gateway
• Send text and markdown replies via the REST API
• Download and process images, voice messages, and file attachments
• Transcribe voice messages using Tencent’s built-in ASR or a configurable STT provider

​

Prerequisites

1. QQ Bot Application — Register at q.qq.com:
   • Create a new application and note your App ID and App Secret
   • Enable the required intents: C2C messages, Group @-messages, Guild messages
   • Configure your bot in sandbox mode for testing, or publish for production
2. Dependencies — The adapter requires aiohttp and httpx:
   python -c "import pm; pm.sync_venv(['messaging'], explicit=True)"
   

​

Configuration

​

Interactive setup

mibyan gateway setup

​

Manual configuration

QQ_APP_ID=your-app-id
QQ_CLIENT_SECRET=your-app-secret

​

Environment Variables

​

Advanced Configuration

platforms:
  qqbot:
    enabled: true
    extra:
      app_id: "your-app-id"
      client_secret: "your-secret"
      markdown_support: true       # enable QQ markdown (msg_type 2). Config-only; no env-var equivalent.
      dm_policy: "open"          # open | allowlist | disabled
      allow_from:
        - "user_openid_1"
      group_policy: "open"       # open | allowlist | disabled
      group_allow_from:
        - "group_openid_1"
      stt:
        provider: "zai"          # zai (GLM-ASR), openai (Whisper), etc.
        baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4"
        apiKey: "your-stt-key"
        model: "glm-asr"
        timeout: 60              # seconds per transcription request (default 60)

​

Voice Messages (STT)

1. QQ built-in ASR (free, always tried first) — QQ provides asr_refer_text in voice message attachments, which uses Tencent’s own speech recognition
2. Configured STT provider (fallback) — If QQ’s ASR doesn’t return text, the adapter calls an OpenAI-compatible STT API:
   • Zhipu/GLM (zai): Default provider, uses glm-asr model
   • OpenAI Whisper: Set QQ_STT_BASE_URL and QQ_STT_MODEL
   • Any OpenAI-compatible STT endpoint

​

Troubleshooting

​

Bot disconnects immediately (quick disconnect)

• Invalid App ID / Secret — Double-check your credentials at q.qq.com
• Missing permissions — Ensure the bot has the required intents enabled
• Sandbox-only bot — If the bot is in sandbox mode, it can only receive messages from QQ’s sandbox test channel

​

Voice messages not transcribed

1. Check if QQ’s built-in asr_refer_text is present in the attachment data
2. If using a custom STT provider, verify QQ_STT_API_KEY is set correctly
3. Check gateway logs for STT error messages

​

Messages not delivered

• Verify the bot’s intents are enabled at q.qq.com
• Check QQ_ALLOWED_USERS if DM access is restricted
• For group messages, ensure the bot is @mentioned (group policy may require allowlisting)
• Check QQBOT_HOME_CHANNEL for cron/notification delivery

​

Connection errors

• Ensure aiohttp and httpx are installed: python -c "import pm; pm.sync_venv(['messaging'], explicit=True)"
• Check network connectivity to api.sgroup.qq.com and the WebSocket gateway
• Review gateway logs for detailed error messages and reconnect behavior