baodan/WECOM_GROUP_CONFIG.md

# 企微群聊消息配置说明

## 问题原因

企微的应用群聊接口 `/cgi-bin/appchat/send` 发送群聊消息需要在企微后台配置"群聊会话"功能。

## 解决方案

### 方案1：使用群机器人 Webhook（单群/指定群）

1. **在企微群里添加群机器人**
   - 打开企业微信，进入目标群聊
   - 点击右上角 `...` -> 群机器人 -> 添加机器人
   - 复制 Webhook 地址

2. **配置环境变量**
    ```bash
    # 历史配置：只适合无 chatid 的兜底场景，不适合多群动态回复
    WECOM_GROUP_WEBHOOK=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_WEBHOOK_KEY
    ```

   如果必须按不同群使用不同 Webhook，可以配置 `chatid` 到 Webhook 的映射：
   ```bash
   WECOM_GROUP_WEBHOOKS={"CHAT_ID_A":"https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=KEY_A","CHAT_ID_B":"https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=KEY_B"}
   ```

> 多个群不能共用一个 `WECOM_GROUP_WEBHOOK`，否则 B 群的问题也会被发送到 A 群。
> 多群请优先使用下面的"群聊会话"方案，按当前回调消息里的 `chatid` 发送。

### 方案2：配置"群聊会话"功能

1. **在企微管理后台配置**
   - 登录 https://work.weixin.qq.com/wework_admin/frame
   - 应用管理 -> 选择你的应用
   - 开启"群聊会话"功能
   - 配置允许接收消息的群聊

2. **确保应用在群里**
   - 将应用机器人添加到目标群聊
   - 或者手动创建群聊会话并邀请机器人

## 验证方法

1. 重启服务后，在群里 @机器人 发送消息
2. 查看日志，确认不再出现 `82001` 错误
3. 机器人应该能正常回复消息

## 错误码说明

| 错误码 | 含义 | 解决方案 |
|--------|------|----------|
| 82001 | touser/toparty/totag/ticket 无效 | 使用群机器人 Webhook 或配置"群聊会话"功能 |
| 40009 | 不合法的文件类型 | 检查消息格式 |
| 40014 | 不合法的 access_token | 检查 WECOM_SECRET 配置 |
| 41001 | 缺少 access_token | 检查企微配置 |
| 45009 | 接口调用超过限制 | 降低调用频率 |