Message Platform Integration#

English ｜ 中文 ｜ Docs Home

ILBB talks to QQ over the OneBot V11 protocol, and the implementation actually deployed in production is NapCat. This document explains clearly: who connects to whom, how to connect, what you can do once connected, and how to troubleshoot when the connection fails.

I. Getting the direction right matters#

ILBB is the WebSocket server; NapCat is the client.

NapCat (logged-in QQ)
      │  Actively initiates a "reverse WebSocket" connection
      ▼
ILBB  core/ws_server.py   listening on 0.0.0.0:6700/onebot/v11/ws

So the configuration action is to fill in ILBB's address inside NapCat, not to fill in NapCat's address inside ILBB. Get the direction backwards and it will never connect.

II. Integration steps#

1. Confirm that the WS server on the ILBB side is running#

Two ways:

• Admin panel —— open /admin and click "Start" in the integration panel;
• Config file —— set WS_AUTO_START=true in .env so it starts together with the main service.

After starting, the terminal prints:

[WS] OneBot V11 WebSocket 服务器已启动 → ws://0.0.0.0:6700/onebot/v11/ws

If WS_ACCESS_TOKEN is configured, one more line "已启用 access_token 校验" will appear.

2. Confirm the IP of the ILBB machine#

• Windows: ipconfig, find the LAN IPv4 (of the form 192.168.x.x)
• Linux: ip -4 addr show or hostname -I

3. Add a reverse WebSocket in NapCat#

In NapCat's WebUI / configuration interface, add a new network configuration item and choose the type Reverse WebSocket:

After saving, NapCat will try to connect immediately.

4. Verify the connection#

Go back to the live event stream in the ILBB admin panel:

• Connected —— the connection count at the top becomes 1 and events start scrolling;
• No reaction —— see the last section of this document for troubleshooting.

Then send a /help in the group; you should receive the image menu.

5. Firewall#

When NapCat and ILBB are not on the same machine, the machine running ILBB must allow port 6700:

# Windows (Administrator PowerShell)
New-NetFirewallRule -DisplayName "ILBB OneBot 6700" -Direction Inbound -Protocol TCP -LocalPort 6700 -Action Allow

# Linux (ufw)
sudo ufw allow 6700/tcp

III. Protocol details#

What ILBB parses is standard OneBot V11 report JSON, and it supports these post_type categories:

Inside a message, ILBB parses these message segments:

Other segment types are ignored. If an entire message contains no text segment at all, ILBB falls back to raw_message.

Calling OneBot APIs proactively#

The reverse direction also works: ILBB can proactively call any OneBot API on NapCat (for example send_group_msg to send a message proactively, or get_group_member_list to pull group members). The API debugger panel in the admin panel ships with parameter metadata for 30+ APIs, automatically rendered into input boxes — one click sends the call.

Grouped by function:

Plugins can call them too, using ctx.call_api(action, params), see plugin-dev.md.

IV. What the admin panel shows#

Open /admin → integration panel:

Configuration precedence#

This is an easy trap to fall into:

If you changed .env but found it did not take effect, it is most likely overridden by ws_config.json —— set this item to env, or simply change it in the panel.

V. REST API overview#

WebUI's own endpoints (/api/*, login required):

The admin backend also keeps API call statistics (the call count of each endpoint is visible in /api/status).

VI. OpenAI-compatible layer /v1#

ILBB exposes an OpenAI-style API layer, so any OpenAI client can call it directly to generate memes.

Authentication: send the header Authorization: Bearer <your API Key>. API Keys are generated and managed on the settings page in the admin panel (and can be disabled).

A typical call:

curl -X POST http://127.0.0.1:5000/v1/images/generations \
  -H "Authorization: Bearer <your API Key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"petpet","prompt":"petpet 头像"}'

Error responses also follow the OpenAI format (error.type / error.param / error.code); a missing or invalid key returns missing_api_key / invalid_api_key respectively.

/v1/* and /api/* use different authentication: the former uses a Bearer API Key, the latter uses a login session.

VII. Troubleshooting a failed connection#

Check in this order and you can basically pinpoint the problem:

1. Is ILBB's WS server up Does the terminal show the line OneBot V11 WebSocket 服务器已启动; is the status in the admin integration panel "Running".
2. Is the address reachable from the machine running NapCat On the machine where NapCat runs, execute:

   curl -v http://192.168.x.x:6700/onebot/v11/ws

If it cannot connect, it is a network / firewall problem (see point 5 of step 2).

3. Does the Token match If one side sets WS_ACCESS_TOKEN and the other leaves it empty (or the two sides differ), the connection will be rejected. Related authentication failure messages will appear in the log.
4. Is the path written correctly The default is /onebot/v11/ws; it is very easy to drop the leading / or mistype it.
5. Is the message format selected correctly On the NapCat side you must choose array. If string is selected, ILBB cannot parse the text / at / image segments.
6. Connected but the bot does not reply Switch to troubleshooting on the command side: whether BOT_ENABLED is true, whether the prefix is right (default /), whether group chats require an @ (BOT_GROUP_NEED_AT), whether private chat is disabled (BOT_ALLOW_PRIVATE), and whether the cooldown is hit (BOT_COOLDOWN_SEC). The "Command Center" in the admin panel can use a dry-run preview to verify command logic on its own, decoupled from network problems.
7. Messages are visible in the event stream, but replies cannot be sent out Look at the return value of can_send_image in the API debugger panel. Also note BOT_MAX_IMAGE_MB (default 8) —— oversized GIF memes will be compressed or dropped.