Skip to content

更新微信公众号部署文档：新增被动回复机制与超时处理说明 #129

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
astrbot-doc-agent wants to merge 1 commit into
base: v4
Choose a base branch
from
Open

更新微信公众号部署文档：新增被动回复机制与超时处理说明 #129

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 50 additions & 42 deletions en/deploy/platform/weixin-official-account.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,83 +1,91 @@
# AstrBot 接入微信公众平台
# AstrBot Integration with WeChat Official Account

AstrBot 支持接入微信公众平台（版本 >= v3.5.8），并以微信公众号的形式接入，届时，您可以直接在微信公众号聊天界面中与 AstrBot 进行交互。
AstrBot supports integration with the WeChat Official Account platform (version >= v3.5.8). You can interact with AstrBot directly through the WeChat Official Account chat interface.

## 准备接入
## Preparation

步骤：
Steps:

1. 进入 AstrBot 的管理面板
2. 点击左边栏 `机器人`
3. 然后在右边的界面中，点击 `+ 创建机器人`
4. 选择 `weixin_official_account(微信公众平台)`
1. Enter the AstrBot management panel.
2. Click `Bot` in the left sidebar.
3. In the right interface, click `+ Create Bot`.
4. Select `weixin_official_account (WeChat Official Account)`.

这将弹出一个对话框。接下来，不要关闭页面，转移到下一步。
A dialog box will pop up. Do not close the page; move to the next step.

## 创建/登入微信公众平台
## Create/Log in to WeChat Official Account Platform

进入[微信公众平台](https://mp.weixin.qq.com/)，如果您需要接入现有的公众号请直接登录即可，如果没有，请点击立即注册然后选择 `公众号` 并填写相关信息注册。
Go to the [WeChat Official Account Platform](https://mp.weixin.qq.com/). If you want to connect an existing account, log in directly. If not, click "Register Now", select "Official Account", and fill in the relevant information to register.

> [!NOTE]
> 新注册的公众号需要花费 1-2 天审核，期间不能使用。
> Newly registered accounts require 1-2 days for review and cannot be used during this period.

## 设置回调服务
## Set up Callback Service

点击 `设置与开发` -> `开发接口管理`。界面如下：
Click `Settings & Development` -> `Development Interface Management`. The interface is as follows:

![开发接口管理](https://files.astrbot.app/docs/source/images/weixin-official-account/image.png)
![Development Interface Management](https://files.astrbot.app/docs/source/images/weixin-official-account/image.png)

记录开发者 ID(AppID) 和开发者密码(AppSecret)，分别填入 AstrBot 配置的 `appid` 和 `secret` 处。
Record the Developer ID (AppID) and Developer Password (AppSecret), and fill them into the `appid` and `secret` fields in the AstrBot configuration.

找到 IP白名单，点击查看，然后添加你的公网 IP 地址。如果有多个公网 IP 地址，换行分隔。
Find the IP Whitelist, click View, and add your public IP address. If there are multiple public IP addresses, separate them with new lines.

找到下方的服务器配置，然后点击修改配置。
Find the Server Configuration below and click "Modify Configuration".

`Token` is filled in by yourself. Please enter any string with a length of 3-32 characters. Fill the same string into the `token` field in the AstrBot configuration (they must be identical).

`Token` 由自己填写，请随意填写一个字符串，长度 3-32 位。并同样填入 AstrBot 配置的 `token` 处（一定要相同）。
`EncodingAESKey`: Click "Random Generate" and copy it to the `encoding_aes_key` field in the AstrBot configuration.

`EncodingAESKey` 请点击随机生成，然后复制到 AstrBot 配置的 `encoding_aes_key` 处。
It is recommended to keep `Unified Webhook Mode (unified_webhook_mode)` enabled.

建议保持 `统一 Webhook 模式 (unified_webhook_mode)` 为开启状态。
Now you should have filled in all the configuration items for AstrBot to connect to the WeChat Official Account platform. Click Save at the bottom right of the AstrBot configuration page and wait for AstrBot to restart.

现在应该已经填完 AstrBot 连接到微信公众平台的所有配置项。点击 AstrBot 配置页右下角保存，等待 AstrBot 重启。
`URL` filling:

`URL` 填写：

- 如果开启了 `统一 Webhook 模式`，点击保存之后，AstrBot 将会自动为你生成唯一的 Webhook 回调链接，你可以在日志中或者 WebUI 的机器人页的卡片上找到，将该链接填入 URL 处。
- If `Unified Webhook Mode` is enabled, after clicking Save, AstrBot will automatically generate a unique Webhook callback link for you. You can find this link in the logs or on the bot card in the WebUI. Fill this link into the URL field.

![unified_webhook](https://files.astrbot.app/docs/source/images/use/unified-webhook.png)

- 如果没有开启 `统一 Webhook 模式`，请填入 `http://你的域名/callback/command`。
- If `Unified Webhook Mode` is not enabled, please enter `http://your-domain/callback/command`.

> Note ⚠️: Only ports 80 or 443 are supported. You may need to purchase a domain and reverse proxy the traffic to port `6185` (if Unified Webhook Mode is enabled) or `6194` (if not enabled) on the server where AstrBot is located, or change the port to 80 (ensure no other software is using port 80).

Select `Security Mode` for the message encryption method.

Wait a moment and click `Submit`. If everything is correct, it will show `Submitted successfully`.

> 注意⚠️：仅支持 80 或者 443 端口。您可能需要购买域名，然后反向代理流量到 AstrBot 所在服务器的 `6185` 端口（如果开启了统一 Webhook 模式）或 `6194` 端口（如果没有开启统一 Webhook 模式），或者将端口改成 80 端口（注意服务器需要没有软件在占用 80 端口）。
## Message Reply Mechanism

消息加解密方式请选中 `安全模式`。
Due to the strict **5-second response time limit** for passive replies on the WeChat Official Account platform, AstrBot has optimized this process:

等待片刻，点击 `提交`。如果一切无误，会显示 `提交成功`。
1. **Timeout Placeholder**: If the AI takes longer than 5 seconds to respond, AstrBot will first return a placeholder message (e.g., `【Thinking about '...', reply any text to try getting the response】`) to prevent the WeChat server from reporting a timeout error.
2. **Message Buffering**: The response generated by the AI will be stored in a buffer.
3. **Retrieve Subsequent Replies**: When you see a placeholder message or a prompt saying "Subsequent messages are still buffering", please **send any text** (e.g., a dot) to the account. AstrBot will then retrieve and send the next segment of the reply from the buffer.
4. **Long Text Chunking**: Long texts are automatically split into chunks of approximately 1024 characters to ensure successful delivery.

## 测试
## Testing

点击左下角你的账号头像，点击账号详情，找到 `二维码`，扫码进入到公众号聊天界面，发送 `help`，看看 AstrBot 是否能够回复。
Click your account avatar in the bottom left corner, click Account Details, find the `QR Code`, scan it to enter the chat interface, and send `help` to see if AstrBot can reply.

如果可以回复，说明接入成功。
If it replies, the integration is successful.

> [!NOTE]
> 如果没有回复，并且控制台报错 `ip xxxxx not in whitelist`，说明你没有添加公网 IP 地址到微信公众平台的 IP 白名单中。如果确认添加了，那请等待若干分钟以让微信服务器更新。
> If there is no reply and the console reports `ip xxxxx not in whitelist`, it means you haven't added the public IP address to the WeChat Official Account platform's IP whitelist. If you are sure it has been added, please wait a few minutes for the WeChat server to update.

## 反向代理(自定义 API BASE)
## Reverse Proxy (Custom API BASE)

AstrBot 支持自定义企业微信的终结点以适应家庭 ip 没有固定的公网 IP 问题。
AstrBot supports custom endpoints for WeChat to adapt to the issue of not having a fixed public IP for home IPs.

只需要将您的自定义地址填入 `api_base_url` 即可。
Just fill your custom address into `api_base_url`.

> 如果您没有公网 ip 当然也可以购买一台服务器，推荐 阿里云 的 99 元/年的服务器。
> If you don't have a public IP, you can also purchase a server.

## 语音输入
## Voice Input

为了语音输入，需要你的电脑上安装有 `ffmpeg`。
For voice input, you need to have `ffmpeg` installed on your computer.

linux 用户可以使用 `apt install ffmpeg` 安装。
Linux users can install it using `apt install ffmpeg`.

windows 用户可以在 [ffmpeg 官网](https://ffmpeg.org/download.html) 下载安装。
Windows users can download and install it from the [ffmpeg official website](https://ffmpeg.org/download.html).

mac 用户可以使用 `brew install ffmpeg` 安装。
Mac users can install it using `brew install ffmpeg`.
11 changes: 10 additions & 1 deletion zh/deploy/platform/weixin-official-account.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,15 @@ AstrBot 支持接入微信公众平台（版本 >= v3.5.8），并以微信公

等待片刻，点击 `提交`。如果一切无误，会显示 `提交成功`。

## 消息回复机制说明

由于微信公众平台对被动回复有严格的 **5 秒响应时间限制**，AstrBot 针对此限制进行了优化：

1. **超时占位符**：如果 AI 响应时间超过 5 秒，AstrBot 会先返回一个占位消息（例如：`【正在思考...，回复任意文字尝试获取回复】`），以防止微信服务器因超时报错。
2. **消息缓冲**：AI 生成的回复会被存储在缓冲区中。
3. **获取后续回复**：当看到占位消息或提示“后续消息还在缓冲中”时，请**发送任意文字**（如一个句号）给公众号，AstrBot 将会从缓冲区中取出并发送下一段回复。
4. **长文本分片**：长文本会被自动切分为约 1024 字符的分片，以确保发送成功。

## 测试

点击左下角你的账号头像，点击账号详情，找到 `二维码`，扫码进入到公众号聊天界面，发送 `help`，看看 AstrBot 是否能够回复。
Expand All @@ -80,4 +89,4 @@ linux 用户可以使用 `apt install ffmpeg` 安装。

windows 用户可以在 [ffmpeg 官网](https://ffmpeg.org/download.html) 下载安装。

mac 用户可以使用 `brew install ffmpeg` 安装。
mac 用户可以使用 `brew install ffmpeg` 安装。