QQ Bot

Connect Hermes to QQ via the Official QQ Bot API (v2) — supporting private (C2C), group @-mentions, guild, and direct messages with voice transcription.

The QQ Bot adapter uses the Official QQ Bot API ↗ to:

• 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

1. QQ Bot Application — Register at q.qq.com ↗:
2. Create a new application and note your App ID and App Secret
3. Enable the required intents: C2C messages, Group @-messages, Guild messages
4. Configure your bot in sandbox mode for testing, or publish for production

1. Dependencies — The adapter requires aiohttp and httpx:

   pip install aiohttp httpx

Interactive setup

hermes gateway setup

Select QQ Bot from the platform list and follow the prompts.

Manual configuration

Set the required environment variables in ~/.hermes/.env:

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

For fine-grained control, add platform settings to ~/.hermes/config.yaml:

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"

Voice transcription works in two stages:

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

Bot disconnects immediately (quick disconnect)

This usually means:

• 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: pip install aiohttp httpx
• Check network connectivity to api.sgroup.qq.com and the WebSocket gateway
• Review gateway logs for detailed error messages and reconnect behavior