---
title: Connect LobeHub to QQ
description: >-
  Learn how to create a QQ bot and connect it to your LobeHub agent as a message
  channel, enabling your AI assistant to chat with users on QQ through group chats and
  direct messages.
tags:
  - QQ
  - Message Channels
  - Bot Setup
  - Integration
---

# Connect LobeHub to QQ

By connecting a QQ channel to your LobeHub agent, users can interact with the AI assistant through QQ group chats, guild channels, and direct messages.

## Prerequisites

- A LobeHub account with an active subscription
- A QQ account

## Connection Modes

LobeHub supports two connection modes for QQ bots:

- **WebSocket (Recommended)** — Persistent connection. Events are delivered in real time via WebSocket. No callback URL configuration required. This is the default mode for new bots.
- **Webhook** — Stateless HTTP callbacks. Use this mode if your bot already has a callback URL configured on the QQ Open Platform and cannot switch.

> **Note:** On the QQ Open Platform, once a bot is configured with a Webhook callback URL, it cannot be switched to WebSocket mode. New bots that have not configured a callback URL should use WebSocket mode.

## Step 1: Create a QQ Bot

<Steps>
  ### Open the QQ Open Platform

  Visit [q.qq.com](https://q.qq.com) and sign in with your QQ account.

  ### Create an Application

  In the QQ Open Platform dashboard, click **Create Bot**. Fill in the bot name, description, and avatar.

  ### Copy App Credentials

  After the application is created, go to **Development Settings** and copy:

  - **App ID** — Your bot's unique identifier
  - **App Secret** — Your bot's secret key

  > **Important:** Keep your App Secret confidential. Never share it publicly.

  ![](/blog/assets276a4e8748e9bd300b30dcd9d0e24980.webp)

  ### Configure Event Delivery (Webhook Only)

  If you are using **Webhook mode**, navigate to **Development Settings** → **Callback Configuration** in the QQ Open Platform. You will need to paste the LobeHub Callback URL here after completing Step 2.

  If you are using **WebSocket mode** (default), skip this step — no callback URL is needed.
</Steps>

## Step 2: Configure QQ in LobeHub

<Steps>
  ### Open Channel Settings

  In LobeHub, navigate to your agent's settings, then select the **Channels** tab. Click **QQ** from the platform list.

  ### Enter App Credentials

  Fill in the following fields:

  - **Application ID** — The App ID from the QQ Open Platform
  - **App Secret** — The App Secret from the QQ Open Platform

  ### Select Connection Mode

  In **Advanced Settings**, choose the **Connection Mode**:

  - **WebSocket** (default) — Recommended for new bots
  - **Webhook** — For bots with an existing callback URL on QQ Open Platform

  ### Save Configuration

  Click **Save Configuration**. Your credentials will be encrypted and stored securely.

  - In **WebSocket mode**, the bot will automatically connect to the QQ gateway. No further configuration is needed.
  - In **Webhook mode**, a **Callback URL** will be displayed after saving. Copy this URL for Step 3.

  ![](/blog/assetsf9317924035e48fcb1d1ae586568ea5f.webp)
</Steps>

## Step 3: Configure Callback in QQ Open Platform (Webhook Only)

> Skip this step if you are using WebSocket mode.

<Steps>
  ### Paste the Callback URL

  Go back to the QQ Open Platform, navigate to **Development Settings** → **Callback Configuration**. Paste the **Callback URL** you copied from LobeHub.

  ### Select Event Types

  Subscribe to the message events your bot needs. Common events include:

  - `GROUP_AT_MESSAGE_CREATE` — Triggered when the bot is @mentioned in a group
  - `C2C_MESSAGE_CREATE` — Triggered when the bot receives a private message
  - `AT_MESSAGE_CREATE` — Triggered when the bot is @mentioned in a guild channel
  - `DIRECT_MESSAGE_CREATE` — Triggered for direct messages in a guild

  ![](/blog/assets737e194726e134bc205a37d74eaee98e.webp)

  ### Verify the Callback

  The QQ Open Platform will send a verification request to your Callback URL. LobeHub handles this automatically using Ed25519 signature verification.
</Steps>

## Step 4: Publish the Bot

<Steps>
  ### Submit for Review

  In the QQ Open Platform, go to **Version Management** and create a new version. Submit the bot for review.

  ### Wait for Approval

  QQ will review your bot. Once approved, the bot will be published and ready to use. For sandbox testing, you can add test users directly without publishing.

  ![](/blog/assets862c2fcdfd3a9e51c44c721c47e1ff5a.webp)
</Steps>

## Step 5: Test the Connection

Click **Test Connection** in LobeHub's channel settings to verify the integration. Then open QQ, find your bot, and send a message. The bot should respond through your LobeHub agent.

## Set Your Platform Identity (Recommended)

One optional field under **Advanced Settings** carries a lot of weight in day-to-day use — fill it in once and most surprises go away.

### Your Platform User ID

This is your own QQ `tiny_id` (the platform-level user identifier — **not** the public-facing QQ number, which doesn't always match), used by:

- **Pairing approval** — required when **DM Policy** is set to **Pairing**, since `/approve <code>` is the owner's command and the runtime checks the sender against this ID.
- **AI tools push** — lets the agent reach you proactively (reminders, notifications) by mapping its internal user reference to your QQ account.
- **Anti-lockout** — auto-trusted by **Allowed Users**, so scoping the bot to friends won't accidentally lock you out.

To get it: DM the bot once with any message and check the server logs for the `tiny_id` field on the inbound event payload (or read it from the OpenAPI dashboard if available). Paste the long numeric ID into **Your Platform User ID** in LobeHub's Advanced Settings.

> QQ doesn't expose a single "default server" concept that AI tools can pivot on, so the **Default Server** field is not exposed for QQ channels.

## Adding the Bot to Group Chats

To use the bot in QQ groups:

1. Add the bot to a QQ group
2. @mention the bot in a message to trigger a response
3. The bot will reply in the group conversation

## Access Policies

Two independent policies gate inbound traffic. Both default to **Open**.

### Allowed User IDs (global)

A populated **Allowed User IDs** field is a global gate — DMs *and* group `@mentions` are restricted to listed QQ `tiny_id` values. Empty means "no user-level filter". Use the platform `tiny_id` from the OpenAPI event payload — the visible QQ number is not always the same as the platform ID.

### DM Policy

- **Open (default)** — Any QQ user who shares context with the bot can DM it (subject to the global allowlist when set).
- **Allowlist** — DMs require the sender to be in **Allowed User IDs**. Differs from `Open` only when the list is empty: `Allowlist` then fails closed (no DMs).
- **Pairing** — Same gate as `Allowlist`, but a non-listed sender receives a one-time pairing code instead of a flat rejection. Approve via `/approve <code>` and the applicant is auto-appended to **Allowed User IDs**. Requires **Your Platform User ID** to be set (the runtime checks the `/approve` sender against it) and a configured Redis backend.
- **Disabled** — The bot ignores all DMs and only responds to group `@mentions`.

### Group Policy

Controls which QQ groups the bot will respond in.

- **Open (default)** — Respond to `@mentions` in any group the bot has been added to.
- **Allowlist** — Respond only in groups whose ID is listed in **Allowed Channel IDs** (use the platform group ID from the OpenAPI event payload).
- **Disabled** — Ignore all group traffic; the bot only responds to DMs.

See the [Channels overview](/docs/usage/channels/overview#direct-message-policy) for cross-platform details.

## Configuration Reference

| Field                   | Required | Description                                                                                          |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| **Application ID**      | Yes      | Your bot's App ID from QQ Open Platform                                                              |
| **App Secret**          | Yes      | Your bot's App Secret from QQ Open Platform                                                          |
| **Connection Mode**     | No       | `websocket` (default) or `webhook`. Choose based on your QQ Open Platform configuration              |
| **Allowed User IDs**    | No       | Comma- or whitespace-separated QQ `tiny_id` values. Global gate — applies to DMs and group @mentions |
| **DM Policy**           | No       | `open` (default), `allowlist`, `pairing`, or `disabled` — who is allowed to DM the bot               |
| **Group Policy**        | No       | `open` (default), `allowlist`, or `disabled` — where the bot responds to @mentions                   |
| **Allowed Channel IDs** | No       | Comma- or whitespace-separated QQ group IDs. Used when Group Policy is Allowlist                     |

## Limitations

- **No message editing** — QQ Bot API does not support editing sent messages. Updated responses will be sent as new messages.
- **No reactions** — QQ Bot API does not support emoji reactions.
- **No typing indicator** — QQ Bot API does not provide typing indicator support for bots.
- **Message length limit** — Messages exceeding 2000 characters will be automatically truncated.

## Troubleshooting

- **Bot not connecting (WebSocket mode):** Verify the App ID and App Secret are correct. Ensure the bot has not been configured with a callback URL on QQ Open Platform — once a callback URL is set, WebSocket mode is unavailable.
- **Callback URL verification failed (Webhook mode):** Ensure you saved the configuration in LobeHub first and the URL was copied correctly. LobeHub handles Ed25519 verification automatically.
- **Bot not responding:** Verify the App ID and App Secret are correct, the bot is published (or you are a sandbox test user), and the required message events are subscribed.
- **Group chat issues:** Make sure the bot has been added to the group. @mention the bot to trigger a response.
- **Test Connection failed:** Double-check the App ID and App Secret in LobeHub's channel settings.
