企业微信发消息接入与问题排查完整指南

企业微信发消息接入与问题排查完整指南

一、基础概念

1. 三个核心参数

• CorpID（企业ID）：在「我的企业 → 企业信息」中获取
• Secret（应用密钥）：在「应用管理 → 自建应用」中获取
• AgentId（应用ID）：在应用详情页中获取

关系：

企业（CorpID）

├── 应用A（AgentId + Secret）

├── 应用B（AgentId + Secret）

---

二、发送消息流程

1. 获取 access_token

GET https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=xxx\&corpsecret=xxx

2. 发送消息

POST https://qyapi.weixin.qq.com/cgi-bin/message/send

示例：

{

"touser": "test_user",

"msgtype": "text",

"agentid": 1000002,

"text": {

"content": "hello"

}

}

---

三、userId 获取方式

路径：

通讯录 → 成员 → 查看账号

注意：

• userId = 账号
• 不是手机号
• 不是姓名

---

四、添加测试用户

步骤：

1. 通讯录 → 添加成员
2. 填写账号（userId）
3. 使用手机号登录企业微信
4. 确保在应用可见范围内

---

五、常见报错：60020

错误：

not allow to access from your ip

原因：

IP 不在白名单

解决：

应用管理 → 应用 → 开发者接口 → IP白名单

---

六、服务商应用 vs 自建应用

类型	是否可控
自建应用	✅ 完全可控
服务商应用	❌ 很多限制

建议：使用自建应用

---

七、域名验证说明

用途：

• 网页授权
• JS-SDK

不影响：

• 发消息接口

---

八、Nginx 配置验证文件

问题

请求被代理导致 502

解决方案

server {

listen 80;

server_name your-domain.com;

location = /WW_verify_xxx.txt {
    root /usr/share/nginx/html;
}

location / {
    proxy_pass http://127.0.0.1:8080;
}

}

文件位置

/usr/share/nginx/html/WW_verify_xxx.txt

---

九、验证步骤

1. nginx -t
2. nginx -s reload
3. 浏览器访问验证文件

---

十、总结

• 发消息核心：CorpID + Secret + AgentId + userId
• 60020 = IP白名单问题
• 域名验证与发消息无关
• Nginx需避免代理验证文件