# 企业微信自建应用接入说明

扫码接入的「企业微信」机器人走官方长连接，只能在企业微信客户端里使用。想在微信里直接对话，用的是自建应用：成员在企业微信后台关注该企业的「微信插件」之后，微信里就能和这个应用互发消息。

这个渠道通过 HTTP 回调接收消息，所以多一步公网配置。下面按实际操作顺序说明，重点讲回调基址怎么填。

## 开始前的准备

- 企业微信管理后台的管理员权限，能创建自建应用。
- 记下应用详情页的企业 ID（CorpID）、AgentId、Secret；在应用的「接收消息 → 设置API接收」里生成 Token 和 EncodingAESKey。
- 一条从公网能访问到本机 30987 端口的通路。腾讯的服务器要能主动连进来，这是 HTTP 回调渠道的硬性要求。

## 绑定步骤

1. 设置 → IM机器人 → 企业微信应用 → 添加企业微信应用，填入六个参数，点「保存并连接」。
2. 保存成功后，卡片上会给出完整的回调 URL。
3. 回到企业微信后台，把回调 URL、Token、EncodingAESKey 填进「接收消息 → 设置API接收」并保存。腾讯会发一条验证请求，插件验签通过即完成绑定。

Token 和 EncodingAESKey 必须和插件卡片里保存的完全一致。后台的「随机生成」每点一次，两边就要同步一次，只改一边会验证失败。企业 ID 也别抄漏字符，它比看上去长。

## 公网回调基址怎么填

绑定表单里的「公网回调基址（可选）」决定回调 URL 的前半段，不填的话插件只能给出路径。两种填法：

**填 IP 加端口**，比如 `http://43.198.123.45:30987`。省事，不需要域名和证书，企业微信也接受 http。前提是公网能访问到这个端口：

- dsh 直接跑在云服务器上时，插件默认只监听 `127.0.0.1`，需要用 iptables、socat 之类做端口转发，或者把插件配置里的 `callbackListenHost` 改成 `0.0.0.0` 后重启。
- dsh 跑在家里或内网机器上时，用 frp 这类内网穿透，把公网服务器的一个端口转回本机 30987。

**填域名**，比如 `https://im.example.com`。适合已经有域名和证书的情况。在 nginx、openresty 或 caddy 里把 `/wecom-app-callback/` 前缀转发到本机 30987 即可，其余路径不受影响：

```nginx
location /wecom-app-callback/ {
    proxy_pass http://127.0.0.1:30987;
    proxy_set_header Host $host;
}
```

走反代之后，插件卡片上展示的回调 URL 就是域名形式，也免得在防火墙上长期开一个端口。

两种方式没有优劣之分，企业微信对 http 和 IP 形式的回调地址都接受。换了基址，回调 URL 会跟着变，记得同步更新企业微信后台。

## 代理地址（可选）

插件调用企业微信 API——取 access_token、发消息，上传媒体文件也不例外——默认直连 `qyapi.weixin.qq.com`。服务器在国内一般留空。服务器在海外时这个域名可能不稳定，可以在一台访问顺畅的机器上做个反代，把 `https://api.example.com` 指向 `https://qyapi.weixin.qq.com`，再把反代地址填进「代理地址」。

出站请求的出口 IP 必须在企业微信后台的「企业可信 IP」列表里：直连填本机公网 IP，走代理填代理服务器的 IP。填错会收到 60020 报错。

## 流式回复

企业微信客户端里回复实时出字。微信端不支持流式接口，插件会自动改成整段发送，无需配置。
在微信插件端和企业微信客户端发给应用的消息，都会进入同一个 DSH 会话，随时切换发送端不影响上下文。但你自己发出的消息不会在另一端镜像显示（企业微信平台行为）：企微客户端里看不到你在微信插件发的消息，微信端也看不到你在企微客户端发的消息；机器人的回复则会在两端同步出现。


## 验证失败时先查这几处

- 后台保存回调提示「验证失败」或「回调地址不通过」：多半是 Token 或 EncodingAESKey 和插件卡片里保存的不一致。浏览器打开 `基址/wecom-app-callback/probe`，返回 404 说明通路是通的；连不上就是网络没打通。
- 能发消息收不到回复：检查企业可信 IP 是否覆盖了出站 IP。
- 日志里 errcode 60020 对应可信 IP 未覆盖，41004 对应 Secret 缺失或不正确。