Build Your Own QQ Bot

Introduction

Recently, I found that the WebUI of NapCatQQ has been improved, making it quite suitable for beginners, so I wrote this article.

This article only covers basic usage methods and may lack some advanced features. However, it also requires understanding the following basics: command line, HTTP protocol, Docker, and Python - it's not completely beginner-friendly. (If you only want to use Webhook for notifications or use existing NoneBot plugins, Python programming is not required.)

The tools used are NapCatQQ and NoneBot. The former runs QQ and connects to protocols like OneBot11, while the latter is a framework based on Python for calling protocols. You can check the official documentation when encountering problems. (If you only want to use Webhook for notifications, setting up NapCatQQ is sufficient.)

Preparation

A server, either internal or external network.
A QQ account to use as the QQ bot. Using your main account is not recommended.

QQ can detect whether plugins are being used, and your account may encounter the following issues: forced logout, login restrictions, or freezing. Please evaluate your own situation and decide whether to continue. The author is not responsible for any consequences of building a bot following this article.

NapCatQQ

Installation

There are many ways to install NapCatQQ, but since it's a service, I recommend using Docker to install the Shell version: https://napneko.github.io/guide/boot/Shell#napcat-docker-linux-containerized-deployment The Docker container comes with NTQQ itself, so you don't need to install the corresponding version of QQ separately.

CodeBlock Loading...

At this point, you can visit http://[IP]:6099/webui to see the NTQQ web page for login and settings. The login password can be found in the log file (default: napcat), and it's recommended to change it after logging in. Alternatively, you can use docker logs napcat to view the logs and scan the QR code to log in to QQ. When scanning to log in, it's recommended to check the option to skip mobile verification in the future.

Enable HTTP Protocol

In the WebUI, find Network Configuration -> New -> HTTP Server. The name, host, and port can be arbitrary. For message format, Array is recommended, but actual testing shows it's compatible with String, and it can send mixed text-image messages. It's strongly recommended to fill in a Token to prevent malicious requests.

After enabling, you can test in API Debug -> HTTP or any other API testing tool you're comfortable with. API reference: https://napcat.apifox.cn/

There are two ways to use the Token:

Add Authorization: [Token] in the request header.

CodeBlock Loading...

Add ?access_token=[Token] in the URL.

CodeBlock Loading...

Using Webhook for Notifications

The most important interfaces here are naturally sending private messages and group messages. You can find the corresponding APIs in API Debug -> HTTP, which also has a message construction feature - it's quite simple. Here's an example of sending a private message:

CodeBlock Loading...

Some applications use shoutrrr as a Webhook implementation. You can refer to the following configuration:

CodeBlock Loading...

Some applications may already support the OneBot11 protocol. In this case, just enter http://[IP]:3000, the Token, and the target QQ number.

nginx Reverse Proxy

If you have a domain name, you can refer to the following nginx configuration example for NapCatQQ:

CodeBlock Loading...

NoneBot

The documentation is already quite comprehensive, so I won't go into detail here.

Introduction

Recently, I found that the WebUI of NapCatQQ has been improved, making it quite suitable for beginners, so I wrote this article.

Preparation

A server, either internal or external network.
A QQ account to use as the QQ bot. Using your main account is not recommended.

NapCatQQ

Installation

BASH

docker run -d \
    -v /data/napcat/QQdata:/app/.config/QQ \      # QQ data directory
    -v /data/napcat/logs:/app/napcat/logs \       # Log directory
    -v /data/napcat/config:/app/napcat/config \   # Configuration directory
    -v /etc/localtime:/etc/localtime:ro \
    --net=host \    # Host network is recommended for connecting to NoneBot later
    --name napcat \
    --restart=always \
    mlikiowa/napcat-docker:latest

CodeBlock Loading...

Enable HTTP Protocol

After enabling, you can test in API Debug -> HTTP or any other API testing tool you're comfortable with. API reference: https://napcat.apifox.cn/

There are two ways to use the Token:

Add Authorization: [Token] in the request header.

BASH

curl -X GET 'http://[IP]:3000/get_friend_list' -H 'Authorization: [Token]'

CodeBlock Loading...

Add ?access_token=[Token] in the URL.

BASH

curl -X GET 'http://[IP]:3000/get_friend_list?access_token=[Token]'

CodeBlock Loading...

Using Webhook for Notifications

BASH

curl -X POST 'http://[IP]:3000/send_private_msg' -H 'Content-Type: application/json' -H 'Authorization: [Token]' -d '{
  "user_id": "[TargetQQ]",
  "message": [
    {
      "type": "text",
      "data": {
        "text": "Hello World!"
      }
    },
    {
      "type": "face",
      "data": {
        "id": "63"
      }
    },
    {
      "type": "image",
      "data": {
        "file": "https://napneko.github.io/assets/newlogo.png"
      }
    }
  ]}'

CodeBlock Loading...

Some applications use shoutrrr as a Webhook implementation. You can refer to the following configuration:

generic://[IP]:3000/send_private_msg?access_token=[Token]&template=json&titleKey=user_id&messageKey=message&@Content-Type=application/json&$user_id=[TargetQQ]

CodeBlock Loading...

Some applications may already support the OneBot11 protocol. In this case, just enter http://[IP]:3000, the Token, and the target QQ number.

nginx Reverse Proxy

If you have a domain name, you can refer to the following nginx configuration example for NapCatQQ:

NGINX

server {
    listen 80;
    listen [::]:80;
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name qq.example.cn;
    access_log /var/log/nginx/access.qq.log;
    error_log /var/log/nginx/error.qq.log;
    location /webui {
        proxy_pass http://127.0.0.1:6099$request_uri;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Real-PORT $remote_port;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
    location /api {
        proxy_pass http://127.0.0.1:6099$request_uri;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Real-PORT $remote_port;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
    location /files {
        proxy_pass http://127.0.0.1:6099$request_uri;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Real-PORT $remote_port;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
    location / {
        if ($request_method = POST) {
            access_log /var/log/nginx/post.qq.log postdata;
        }
        proxy_pass http://127.0.0.1:3000$request_uri;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Real-PORT $remote_port;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

CodeBlock Loading...

NoneBot

The documentation is already quite comprehensive, so I won't go into detail here.