mirror of
https://github.com/zhayujie/chatgpt-on-wechat.git
synced 2026-06-02 00:57:41 +08:00
docs: add WeCom customer service (wechatcom_kf) channel guide
Add a self-deployment guide for the new `wechatcom_kf` channel under `docs/channels/wecom-kf.mdx` in zh / en / ja, mirroring the existing `wecom.mdx` structure. Wire each language version into the sidebar in `docs/docs.json`. Walks through: creating the WeCom custom app, retrieving Corp ID / Secret (push-to-phone) / Token / EncodingAESKey, configuring `config.json`, saving the callback URL + Enterprise Trusted IPs, binding the WeCom Customer Service account, and distributing the access link / QR code. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
6vision
119
docs/channels/wecom-kf.mdx
Normal file
119
docs/channels/wecom-kf.mdx
Normal file
@@ -0,0 +1,119 @@
|
||||
---
|
||||
title: 微信客服
|
||||
description: 将 CowAgent 接入微信客服（WeCom Customer Service）
|
||||
---
|
||||
|
||||
通过把企业微信自建应用绑定到「微信客服」账号，CowAgent 可以接管来自外部微信用户的客服咨询，并可在小程序、公众号、视频号及视频号小店等场景中通过链接或二维码触达微信用户。
|
||||
|
||||
<Note>
|
||||
微信客服只能使用 Docker 部署或服务器 Python 部署，需要公网可达的回调地址，不支持本地运行模式。
|
||||
</Note>
|
||||
|
||||
## 一、准备
|
||||
|
||||
需要的资源：
|
||||
|
||||
1. 一台服务器（有公网 IP）
|
||||
2. 注册并已认证的企业微信
|
||||
3. 已开通「微信客服」能力
|
||||
|
||||
<Note>
|
||||
建议**单独再创建一个企微自建应用**用于微信客服，不要复用已有的 `wechatcom_app` 应用，否则两个通道会争抢同一个回调地址。
|
||||
</Note>
|
||||
|
||||
## 二、创建企业微信自建应用
|
||||
|
||||
1. 在 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#apps)，点击 **应用管理 → 创建应用**：
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/20260228103156.png" width="480"/>
|
||||
|
||||
2. 点击 **我的企业**，在最下方获取 **企业ID**（后续填写到 `wechatcom_corp_id`）：
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/wechatcom-hosting-companyid.png" width="600"/>
|
||||
|
||||
3. 进入上一步创建的应用，点击 Secret 旁的「**查看**」，Secret 会推送到管理员手机端的企业微信里查看：
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/wechatcom-hosting-agent-secret.png" width="600"/>
|
||||
|
||||
4. 进入应用 **接收消息 → 设置API接收**，点击右侧「**随机获取**」生成 **Token** 和 **EncodingAESKey** 并保存：
|
||||
|
||||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wechatcom-hosting-token-aeskey.jpg" width="600"/>
|
||||
|
||||
<Note>
|
||||
此时保存 API 接收配置会失败，因为程序还未启动，等项目运行后再回来保存。
|
||||
</Note>
|
||||
|
||||
## 三、配置和运行
|
||||
|
||||
在 `config.json` 中添加以下配置（各参数与企业微信后台的对应关系见上方截图）：
|
||||
|
||||
```json
|
||||
{
|
||||
"channel_type": "wechatcom_kf",
|
||||
"wechatcom_corp_id": "YOUR_CORP_ID",
|
||||
"wechatcom_kf_secret": "YOUR_SECRET",
|
||||
"wechatcom_kf_token": "YOUR_TOKEN",
|
||||
"wechatcom_kf_aes_key": "YOUR_AES_KEY",
|
||||
"wechatcom_kf_port": 9888
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 说明 |
|
||||
| --- | --- |
|
||||
| `wechatcom_corp_id` | 企业 ID |
|
||||
| `wechatcom_kf_secret` | 绑定到微信客服的那个企微自建应用的 Secret |
|
||||
| `wechatcom_kf_token` | API 接收配置中的 Token |
|
||||
| `wechatcom_kf_aes_key` | API 接收配置中的 EncodingAESKey |
|
||||
| `wechatcom_kf_port` | 监听端口，默认 9888 |
|
||||
|
||||
配置完成后启动程序。当日志中出现 `Listening on http://0.0.0.0:9888/wxkf/` 时，说明程序运行成功，需要将该端口对外开放（如在云服务器安全组中放行）。
|
||||
|
||||
程序启动后，回到企业微信「接收消息 → 设置API接收」，将回调 URL 填为 `http://<your-host>:9888/wxkf/`，点击保存。保存成功后还需将服务器 IP 添加到 **企业可信IP** 中，否则无法收发消息：
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/wechat-com_config.png" width="600"/>
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/20260228103224.png" width="520"/>
|
||||
|
||||
<Warning>
|
||||
如遇到 URL 配置回调不通过或配置失败：
|
||||
1. 确保服务器防火墙关闭且安全组放行监听端口（默认 9888）
|
||||
2. 仔细检查 Token、Secret、EncodingAESKey 等参数配置是否一致，URL 格式是否正确
|
||||
3. 认证企业微信需要配置与主体一致的备案域名
|
||||
</Warning>
|
||||
|
||||
## 四、绑定微信客服账号
|
||||
|
||||
进入企业微信管理后台 **微信客服** 页面，创建客服账号并与上一步的企微自建应用绑定：
|
||||
|
||||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step1.jpg" width="600"/>
|
||||
|
||||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step2.jpg" width="600"/>
|
||||
|
||||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step3.jpg" width="600"/>
|
||||
|
||||
绑定完成后，进入 **微信客服 → 微信客服账号详情**，在「**接入链接**」一栏：
|
||||
|
||||
- 点击「**复制链接**」可获得形如 `https://work.weixin.qq.com/kfid/kfcd83e5896b9ba07be` 的访问链接
|
||||
- 点击「**生成二维码**」可获得对应的二维码
|
||||
|
||||
把链接或二维码推给微信客户使用即可：
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/wechat-customer-service_use.png" width="600"/>
|
||||
|
||||
## 五、使用
|
||||
|
||||
微信用户通过链接或二维码进入客服对话后，即可与 AI 进行多轮对话，支持文本、图片、语音等消息：
|
||||
|
||||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-chat-demo.jpg" width="900"/>
|
||||
|
||||
除此之外，基于微信生态官方能力，还可将微信客服应用在公众号、小程序、视频号及视频号小店等场景，详情可查看企业微信管理后台 [微信客服 → 接入场景](https://work.weixin.qq.com/wework_admin/frame#/app/servicer) 的相关说明：
|
||||
|
||||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-interface-demo.png" width="800"/>
|
||||
|
||||
## 常见问题
|
||||
|
||||
需要确保已安装以下依赖：
|
||||
|
||||
```bash
|
||||
pip install websocket-client pycryptodome
|
||||
```
|
||||
@@ -188,6 +188,7 @@
|
||||
"channels/wecom-bot",
|
||||
"channels/qq",
|
||||
"channels/wecom",
|
||||
"channels/wecom-kf",
|
||||
"channels/wechatmp"
|
||||
]
|
||||
}
|
||||
@@ -380,6 +381,7 @@
|
||||
"en/channels/wecom-bot",
|
||||
"en/channels/qq",
|
||||
"en/channels/wecom",
|
||||
"en/channels/wecom-kf",
|
||||
"en/channels/wechatmp"
|
||||
]
|
||||
}
|
||||
@@ -574,6 +576,7 @@
|
||||
"ja/channels/wecom-bot",
|
||||
"ja/channels/qq",
|
||||
"ja/channels/wecom",
|
||||
"ja/channels/wecom-kf",
|
||||
"ja/channels/wechatmp"
|
||||
]
|
||||
}
|
||||
|
||||
119
docs/en/channels/wecom-kf.mdx
Normal file
119
docs/en/channels/wecom-kf.mdx
Normal file
@@ -0,0 +1,119 @@
|
||||
---
|
||||
title: WeCom Customer Service
|
||||
description: Integrate CowAgent into WeCom Customer Service (微信客服)
|
||||
---
|
||||
|
||||
By binding a WeCom custom enterprise app to a WeCom Customer Service (微信客服) account, CowAgent can take over inbound inquiries from external WeChat users and serve them through links or QR codes embedded in WeChat Mini Programs, Official Accounts, Video Channels, and Video Channel stores.
|
||||
|
||||
<Note>
|
||||
WeCom Customer Service only supports Docker deployment or server Python deployment. A publicly reachable callback URL is required; local run mode is not supported.
|
||||
</Note>
|
||||
|
||||
## 1. Prerequisites
|
||||
|
||||
Required resources:
|
||||
|
||||
1. A server with a public IP
|
||||
2. A registered and verified WeCom account
|
||||
3. WeCom Customer Service capability enabled
|
||||
|
||||
<Note>
|
||||
It is recommended to create a **dedicated** WeCom custom app for Customer Service rather than reusing the existing `wechatcom_app` one — otherwise the two channels will compete for the same callback URL.
|
||||
</Note>
|
||||
|
||||
## 2. Create a WeCom Custom App
|
||||
|
||||
1. In the [WeCom Admin Console](https://work.weixin.qq.com/wework_admin/frame#apps), go to **Application Management → Create Application**:
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/20260228103156.png" width="480"/>
|
||||
|
||||
2. Click **My Enterprise** and find the **Corp ID** at the bottom of the page (it goes into `wechatcom_corp_id`):
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/wechatcom-hosting-companyid.png" width="600"/>
|
||||
|
||||
3. Open the app you just created and click **"View"** next to Secret. The Secret will be pushed to the admin's phone via the WeCom app, where it can be viewed:
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/wechatcom-hosting-agent-secret.png" width="600"/>
|
||||
|
||||
4. Open the app's **Receive Messages → Set API Reception** page, click **"Random Generate"** to generate the **Token** and **EncodingAESKey**, and save them:
|
||||
|
||||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wechatcom-hosting-token-aeskey.jpg" width="600"/>
|
||||
|
||||
<Note>
|
||||
Saving the API reception configuration will fail at this point because the program has not started yet. Come back to save it after the project is running.
|
||||
</Note>
|
||||
|
||||
## 3. Configuration and Run
|
||||
|
||||
Add the following configuration to `config.json` (each parameter maps to a field shown in the screenshots above):
|
||||
|
||||
```json
|
||||
{
|
||||
"channel_type": "wechatcom_kf",
|
||||
"wechatcom_corp_id": "YOUR_CORP_ID",
|
||||
"wechatcom_kf_secret": "YOUR_SECRET",
|
||||
"wechatcom_kf_token": "YOUR_TOKEN",
|
||||
"wechatcom_kf_aes_key": "YOUR_AES_KEY",
|
||||
"wechatcom_kf_port": 9888
|
||||
}
|
||||
```
|
||||
|
||||
| Parameter | Description |
|
||||
| --- | --- |
|
||||
| `wechatcom_corp_id` | Corp ID |
|
||||
| `wechatcom_kf_secret` | Secret of the WeCom custom app bound to Customer Service |
|
||||
| `wechatcom_kf_token` | Token from the API reception config |
|
||||
| `wechatcom_kf_aes_key` | EncodingAESKey from the API reception config |
|
||||
| `wechatcom_kf_port` | Listening port, default 9888 |
|
||||
|
||||
After configuration, start the program. When the log shows `Listening on http://0.0.0.0:9888/wxkf/`, the program is running successfully. You need to open this port externally (e.g., allow it in the cloud server security group).
|
||||
|
||||
Once the program is running, go back to **Receive Messages → Set API Reception** in the WeCom console and set the callback URL to `http://<your-host>:9888/wxkf/`, then click Save. After saving successfully, you also need to add the server IP to **Enterprise Trusted IPs**, otherwise messages cannot be sent or received:
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/wechat-com_config.png" width="600"/>
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/20260228103224.png" width="520"/>
|
||||
|
||||
<Warning>
|
||||
If URL verification fails or the configuration is unsuccessful:
|
||||
1. Ensure the server firewall is disabled and the security group allows the listening port (default 9888)
|
||||
2. Carefully check that Token, Secret, EncodingAESKey and other parameters are consistent, and the URL format is correct
|
||||
3. Verified WeCom accounts must use a filed domain matching the entity
|
||||
</Warning>
|
||||
|
||||
## 4. Bind a WeCom Customer Service Account
|
||||
|
||||
In the WeCom Admin Console, go to **WeCom Customer Service**, create a customer service account, and bind it to the custom app you created above:
|
||||
|
||||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step1.jpg" width="600"/>
|
||||
|
||||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step2.jpg" width="600"/>
|
||||
|
||||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step3.jpg" width="600"/>
|
||||
|
||||
After binding, go to **WeCom Customer Service → Account Details**, and under **"Access Link"**:
|
||||
|
||||
- Click **"Copy Link"** to get an access link like `https://work.weixin.qq.com/kfid/kfcd83e5896b9ba07be`
|
||||
- Click **"Generate QR Code"** to get the corresponding QR code
|
||||
|
||||
Distribute the link or QR code to your WeChat customers:
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/wechat-customer-service_use.png" width="600"/>
|
||||
|
||||
## 5. Usage
|
||||
|
||||
After WeChat users enter the customer service conversation via the link or QR code, they can chat with the AI across multiple turns, with support for text, image, and voice messages:
|
||||
|
||||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-chat-demo.jpg" width="900"/>
|
||||
|
||||
Beyond that, leveraging the official WeChat ecosystem, WeCom Customer Service can also be embedded into Official Accounts, Mini Programs, Video Channels and more. See the **WeCom Customer Service → Access Scenarios** section in the [WeCom Admin Console](https://work.weixin.qq.com/wework_admin/frame#/app/servicer) for details:
|
||||
|
||||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-interface-demo.png" width="800"/>
|
||||
|
||||
## FAQ
|
||||
|
||||
Make sure the following dependencies are installed:
|
||||
|
||||
```bash
|
||||
pip install websocket-client pycryptodome
|
||||
```
|
||||
119
docs/ja/channels/wecom-kf.mdx
Normal file
119
docs/ja/channels/wecom-kf.mdx
Normal file
@@ -0,0 +1,119 @@
|
||||
---
|
||||
title: WeChat カスタマーサービス
|
||||
description: CowAgent を 微信客服（WeCom Customer Service）に統合する
|
||||
---
|
||||
|
||||
WeCom の自建アプリを「微信客服（WeCom Customer Service）」アカウントにバインドすることで、CowAgent は外部 WeChat ユーザーからの問い合わせを引き受けることができます。WeChat ミニプログラム、公式アカウント、ビデオチャンネル、ビデオチャンネルストアなどから、リンクや QR コードで WeChat ユーザーに到達できます。
|
||||
|
||||
<Note>
|
||||
WeChat カスタマーサービスは Docker デプロイまたはサーバー Python デプロイのみサポートしており、外部からアクセス可能なコールバック URL が必要です。ローカル実行モードには対応していません。
|
||||
</Note>
|
||||
|
||||
## 1. 前提条件
|
||||
|
||||
必要なリソース：
|
||||
|
||||
1. パブリック IP を持つサーバー
|
||||
2. 登録済みかつ認証済みの WeCom アカウント
|
||||
3. 「微信客服」機能が有効になっていること
|
||||
|
||||
<Note>
|
||||
カスタマーサービス専用に **新たな** 企業微信自建アプリを作成することを推奨します。既存の `wechatcom_app` アプリを流用すると、2 つのチャネルが同じコールバック URL を奪い合うことになります。
|
||||
</Note>
|
||||
|
||||
## 2. 企業微信自建アプリの作成
|
||||
|
||||
1. [WeCom 管理コンソール](https://work.weixin.qq.com/wework_admin/frame#apps) で **アプリ管理 → アプリ作成** をクリックします：
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/20260228103156.png" width="480"/>
|
||||
|
||||
2. **自社情報** をクリックし、ページ下部で **企業ID（Corp ID）** を確認します（`wechatcom_corp_id` に設定します）：
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/wechatcom-hosting-companyid.png" width="600"/>
|
||||
|
||||
3. 上で作成したアプリに入り、Secret の隣の「**表示**」をクリックします。Secret は管理者のスマートフォンの WeCom アプリに送られ、そこで確認できます：
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/wechatcom-hosting-agent-secret.png" width="600"/>
|
||||
|
||||
4. アプリの **メッセージ受信 → API 受信設定** に入り、右側の「**ランダム生成**」をクリックして **Token** と **EncodingAESKey** を生成し、保存します：
|
||||
|
||||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wechatcom-hosting-token-aeskey.jpg" width="600"/>
|
||||
|
||||
<Note>
|
||||
プログラムがまだ起動していないため、この時点では API 受信設定を保存できません。プロジェクトが動作した後に戻って保存してください。
|
||||
</Note>
|
||||
|
||||
## 3. 設定と起動
|
||||
|
||||
`config.json` に以下の設定を追加します（各パラメータと WeCom コンソールの対応関係は上のスクリーンショットを参照してください）：
|
||||
|
||||
```json
|
||||
{
|
||||
"channel_type": "wechatcom_kf",
|
||||
"wechatcom_corp_id": "YOUR_CORP_ID",
|
||||
"wechatcom_kf_secret": "YOUR_SECRET",
|
||||
"wechatcom_kf_token": "YOUR_TOKEN",
|
||||
"wechatcom_kf_aes_key": "YOUR_AES_KEY",
|
||||
"wechatcom_kf_port": 9888
|
||||
}
|
||||
```
|
||||
|
||||
| パラメータ | 説明 |
|
||||
| --- | --- |
|
||||
| `wechatcom_corp_id` | 企業 ID |
|
||||
| `wechatcom_kf_secret` | カスタマーサービスにバインドした企業微信自建アプリの Secret |
|
||||
| `wechatcom_kf_token` | API 受信設定の Token |
|
||||
| `wechatcom_kf_aes_key` | API 受信設定の EncodingAESKey |
|
||||
| `wechatcom_kf_port` | リスンポート、デフォルトは 9888 |
|
||||
|
||||
設定後、プログラムを起動します。ログに `Listening on http://0.0.0.0:9888/wxkf/` と表示されれば、プログラムは正常に動作しています。このポートを外部に公開する必要があります（例：クラウドサーバーのセキュリティグループで許可します）。
|
||||
|
||||
プログラム起動後、WeCom 管理コンソールの **メッセージ受信 → API 受信設定** に戻り、コールバック URL に `http://<your-host>:9888/wxkf/` を入力して保存します。保存が成功したら、サーバー IP を **企業の信頼済み IP** に追加する必要もあります。追加しないとメッセージの送受信ができません：
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/wechat-com_config.png" width="600"/>
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/20260228103224.png" width="520"/>
|
||||
|
||||
<Warning>
|
||||
URL のコールバック検証が通らない、または設定がうまくいかない場合：
|
||||
1. サーバーのファイアウォールが無効になっており、セキュリティグループでリスンポート（デフォルト 9888）が許可されていることを確認してください
|
||||
2. Token、Secret、EncodingAESKey などのパラメータが一致しているか、URL の形式が正しいか慎重に確認してください
|
||||
3. 認証済みの WeCom アカウントは、法人に対応する届け出済みドメインを設定する必要があります
|
||||
</Warning>
|
||||
|
||||
## 4. 微信客服アカウントとのバインド
|
||||
|
||||
WeCom 管理コンソールの **微信客服** ページに入り、カスタマーサービスアカウントを作成し、上で作成した企業微信自建アプリとバインドします：
|
||||
|
||||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step1.jpg" width="600"/>
|
||||
|
||||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step2.jpg" width="600"/>
|
||||
|
||||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step3.jpg" width="600"/>
|
||||
|
||||
バインド完了後、**微信客服 → 微信客服アカウント詳細** に入り、「**接入リンク**」の項目で：
|
||||
|
||||
- 「**リンクをコピー**」をクリックすると、`https://work.weixin.qq.com/kfid/kfcd83e5896b9ba07be` のような接入リンクが取得できます
|
||||
- 「**QR コード生成**」をクリックすると、対応する QR コードが取得できます
|
||||
|
||||
リンクまたは QR コードを WeChat 顧客に配布してください：
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/wechat-customer-service_use.png" width="600"/>
|
||||
|
||||
## 5. 使い方
|
||||
|
||||
WeChat ユーザーがリンクや QR コードからカスタマーサービス対話に入った後、AI とテキスト・画像・音声などのマルチターン対話が可能です：
|
||||
|
||||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-chat-demo.jpg" width="900"/>
|
||||
|
||||
これに加え、WeChat 公式エコシステムの機能に基づき、微信客服を公式アカウント、ミニプログラム、ビデオチャンネルなどの場面でも使用できます。詳細は [WeCom 管理コンソール](https://work.weixin.qq.com/wework_admin/frame#/app/servicer) の **微信客服 → 接入シナリオ** を参照してください：
|
||||
|
||||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-interface-demo.png" width="800"/>
|
||||
|
||||
## FAQ
|
||||
|
||||
以下の依存パッケージがインストールされていることを確認してください：
|
||||
|
||||
```bash
|
||||
pip install websocket-client pycryptodome
|
||||
```
|
||||
Reference in New Issue
Block a user