QQ Integration

The QQ channel is currently in dev. It is recommended for testing, integration checks, and validation before production use.

Required config

{
  "services": {
    "chat": {
      "channels": {
        "qq": {
          "enabled": true,
          "channelAccountId": "qq-main"
        }
      }
    }
  }
}

Credential source:

Create qq-main in Console UI Global / Channel Accounts.
Fill appId, appSecret, and optional sandbox in that channel account.

Start runtime

city agent start

Verify channel status

city service status chat

Group behavior

Group messages are accepted directly (no @mention required).
If your bot only receives @ messages, verify QQ platform event permissions (especially GROUP_MESSAGE_CREATE).

When the asr plugin is enabled and its transcription config under plugins.asr is ready, QQ inbound voice/audio attachments are transcribed in best-effort mode and the transcript is appended to the user instruction.

Recommended setup:

city asr on SenseVoiceSmall
city asr status

Notes:

Transcription failures do not break the main chat flow.
QQ voice attachment delivery depends on gateway AUDIO_ACTION capability. If your bot app does not have that permission, audio payload fields may be missing.

Troubleshooting

Looks connected but replies are missing: runtime now checks heartbeat ACK liveness. When status becomes heartbeat_timeout, QQ channel will auto-reconnect. You can also run city chat reconnect --channel qq.
Inbound works but outbound reply fails: reply sending now does one automatic retry on transient auth/network errors and triggers self-healing reconnect. If it still fails, inspect logs for QQ send failed details (HTTP status + response body).

QQ