很多刚开始做企业微信自建应用的朋友，第一次在管理后台看到“接收消息”配置项时，多少都有点懵。这个开关一旦打开，应用就能通过API接收到用户发送给它的消息内容，然后你可以在自己的服务里对这些内容做各种处理：自动回复、关键词匹配、工单创建、智能客服、内部查询助手……本质上就是给企业微信里的“应用”装上耳朵。这篇文章我就把“企业微信应用开启API接收信息来读取用户发送内容”这条链路从头到尾拆一遍，包含配置步骤、回调原理、签名加解密的代码示例、常见坑和排查方法。适合正要接入回调的开发者，也适合需要评估方案的运维或产品同学。
1. 先搞清楚：为什么需要“API接收信息”这条管道
1.1 应用消息和聊天消息是两码事
很多刚接触的人会把“企业微信API接收消息”和“读取员工聊天记录”混在一起，这是第一个需要纠正的认知。企业微信里的消息分成好几类：成员之间私聊、群聊、客户联系消息、应用会话消息。我们这里讨论的，只是“用户主动给企业微信自建应用发送的消息”和“用户进入应用、点击菜单等事件”。换句话说，这条管道读取的是“应用会话”里的内容，不是员工平时的工作聊天记录。
这两者的权限边界完全不同。普通聊天记录属于企业敏感数据，默认状态下任何第三方应用都拿不到；而用户发给应用的消息，是企业微信明确开放给自建应用开发者的合法数据源。你通过API接收消息这个能力，本质上是在“用户触发应用”的场景里做业务闭环，不是在做监控。
1.2 开启回调前需要先确认的权限边界
在动手配置之前，我建议你先想清楚三件事：应用的用户是谁、可见范围是谁、消息内容用来做什么。企业微信后台创建自建应用时，可以设置“应用可见范围”，只有范围内的人才能在客户端里看到这个应用并给它发消息。如果你的目标是全员可用，可见范围就选全员；如果只是某个部门使用，就只勾选对应部门。
另一个容易忽略的点是“企业可信IP”。如果你不仅接收消息，还要调用企业微信的API去主动回复或查询通讯录，那服务端调用接口的出口IP必须配置到“企业可信IP”列表里，否则接口会报错。这个配置在管理后台的“安全与管理”里，填的是你服务器对外访问的公网IP，不能填内网地址。
1.3 典型应用场景有哪些
这项能力的价值在于“把企业微信当入口，把业务系统当大脑”。我见过并且实际做过的场景大概有这几种：
- 内部值班机器人：员工在企业微信里向应用发“查订单”“查库存”，后端对接现有系统，返回结构化结果。
- 工单流转入口：用户通过应用提交故障描述，系统解析内容后自动创建工单，并通过应用回复工单编号。
- 审批与信息查询：对接企业内部OA，发送关键字即可拉起流程、查询状态。
- 简单问答机器人：不接大模型时，先用关键词规则实现菜单式问答。
这些场景的共同点是：用户只在一个聊天窗口里完成操作，体验非常轻。对后台系统来说，输入是纯文本或多媒体消息，输出是一段回复，链路清晰，适合快速迭代。
2. 开启API接收消息前的基础配置
2.1 创建自建应用并拿到AgentId和Secret
打开企业微信管理后台，进入“应用管理-自建应用”，点击“创建应用”。填好应用名称、头像、可见范围后，你会得到一个AgentId（应用ID）和CorpId（企业ID）。CorpId在“我的企业-企业信息”里查看，AgentId在应用详情页顶部。
接着在应用详情页里找到“Secret”，点“查看”后会发送到企业微信的“微工作台”或管理员的企业微信消息里，注意Secret只会完整展示一次，之后不再显示。如果丢了，只能重置。我的习惯是拿到Secret后立刻放到服务器环境变量里，并且不要在代码仓库里明文提交。
创建应用时还要设置“应用主页”和“工作台展示”等可选信息，这些不影响消息接收，可以先跳过。但“接收消息”这个入口需要单独配置，也就是下一步。
2.2 配置接收消息的URL、Token与EncodingAESKey
在应用详情页里找到“接收消息”，点击“设置API接收”。这里需要填三项：
- URL：你的服务用来接收回调的地址，必须是公网可访问的HTTP或HTTPS地址。企业微信官方要求用HTTPS，但实际测试时HTTP也可以，生产环境我强烈建议上HTTPS，原因后面讲。
- Token：你自己生成的一个随机字符串，用来参与签名校验，相当于一个共享密钥。可以用随机字符生成工具生成，长度建议在16位以上。
- EncodingAESKey：用于加解密消息内容的对称密钥。可以在后台直接点“随机生成”，得到43位字符，保存好。
这里有个小细节：URL不要带query参数，比如https://example.com/callback?type=1这种形式很容易导致验证失败。某些情况下带参数也能通过，但为了稳定，统一用不带参数的干净URL。路径则可以自定义，比如/wecom/callback。
2.3 可信IP与域名校验里的小坑
很多人在配置完成后，调API报错提示“notAllowToVisit”或者“ip not in allow list”，就是因为可信IP没有加对。登录企业微信管理后台，路径是“安全与管理-管理工具-通讯录同步”？不对，是“我的企业-微工作台”？我记忆里的准确路径是：“应用管理-应用-自建应用-企业可信IP”，也有版本是在“安全与管理”里。你搜索“可信IP”就能找到。
填可信IP时，填你服务器出口的公网IP即可。如果你用的是云服务器，出口IP就是云主机的外网IP，可以在服务器上执行curl ifconfig.me查看。如果你在本地开发、用内网穿透工具把回调URL暴露到公网，那么穿透工具的出口IP也要加进去，不然接收消息本身也许不受影响，但调用接口主动回消息时会失败。
另外，URL校验阶段企业微信服务器会向你的URL发起GET请求，如果你的服务器上有防火墙或安全组，需要放行企业微信回调服务器的IP段。这个IP段官方文档有公布，但实际排查中大部分“URL验证失败”其实不是IP封禁，而是代码逻辑问题，我们后面详细讲。
3. 消息回调的核心原理与签名校验
3.1 回调请求长什么样
企业微信的回调分为两步。第一步是“URL验证”，当你保存“接收消息”配置时，企业微信服务器会向你的URL发送一个GET请求，带上四个参数：msg_signature、timestamp、nonce、echostr。你的服务器需要验证签名，然后解密echostr，再把解密后的明文原样返回，配置才能保存成功。
第二步是“真实消息”。之后用户给应用发消息时，企业微信服务器会向你的URL发送POST请求，body是XML格式，核心字段只有一个<Encrypt>标签，里面存放的是整个消息XML的密文，同时Query参数里也有msg_signature、timestamp、nonce。
第一次接触的人容易懵的是：好像没看到明文内容。没错，企业微信对消息体做了AES加密，目的是防止消息在传输过程中被窃取和篡改。所以你必须完成“验签+解密”两步，才能拿到真正的用户消息。
3.2 签名计算与加解密流程
签名校验的逻辑并不复杂。假设你配置的Token为token，回调URL收到的参数里有timestamp和nonce，而POST的body解析出的Encrypt字段值为encrypt。那么把这四个字符串按字典序排序后拼接成一个字符串，再计算SHA-1哈希，得到的结果就是期望的msg_signature。
用公式表示就是：
sort_str = sort([token, timestamp, nonce, encrypt]).join('') signature = sha1(sort_str)注意排序是字典序，不是按参数名长度。如果计算出的签名和请求里的msg_signature不一致，直接拒绝这次请求并返回错误。
解密则使用AES-256-CBC算法。具体来说：
- 把EncodingAESKey末尾拼上一个
=，使其长度为44位，然后用Base64解码，得到32字节的AES密钥。 - IV（初始向量）取这个32字节密钥的前16字节。
- 把
encrypt字符串从Base64解码，得到密文。 - 用AES-256-CBC解密后，得到的是带有PKCS#7填充的明文。去掉填充后，再按固定格式解析出XML内容。
固定格式是指：解密后的明文是一个XML字符串，比如：
<xml> <ToUserName><![CDATA[ww1234567890]]></ToUserName> <FromUserName><![CDATA[zhangsan]]></FromUserName> <CreateTime>1700000000</CreateTime> <MsgType><![CDATA[text]]></MsgType> <Content><![CDATA[你好]]></Content> <MsgId>1234567890123456789</MsgId> <AgentID>1000002</AgentID> </xml>解密后的内容才是业务真正需要的数据。
3.3 一个可直接参考的验签与解密实现
我用Python写过一个比较精简的版本，依赖只有pycryptodome。核心代码如下：
import base64 import hashlib import xml.etree.ElementTree as ET from Crypto.Cipher import AES class WeComCallback: def __init__(self, token, encoding_aes_key): self.token = token self.aes_key = base64.b64decode(encoding_aes_key + "=") self.iv = self.aes_key[:16] def verify_signature(self, msg_signature, timestamp, nonce, encrypt): sort_list = sorted([self.token, timestamp, nonce, encrypt]) sort_str = "".join(sort_list).encode("utf-8") sha1_val = hashlib.sha1(sort_str).hexdigest() return sha1_val == msg_signature def decrypt(self, encrypt): cipher = AES.new(self.aes_key, AES.MODE_CBC, self.iv) plaintext_padded = cipher.decrypt(base64.b64decode(encrypt)) # 去掉PKCS#7填充 pad_len = plaintext_padded[-1] if pad_len < 1 or pad_len > 32: raise ValueError("Invalid padding length") plaintext = plaintext_padded[:-pad_len] return plaintext.decode("utf-8")decrypt返回的就是XML明文。你可以在收到POST请求时先用verify_signature校验，再调用decrypt解析，然后交给业务逻辑处理。
有几点要特别注意：得到plaintext后，最好用xml.etree.ElementTree解析，但是企业微信的XML里有CDATA，直接fromstring是没问题的，只要字段用text属性读取。另外，如果你用的是Java，可以用MessageDigest做SHA-1；用Go可以用crypto/sha1。算法都一样，关键是把字符串排序和Base64解码做对。
4. 从URL验证到真实消息解析的完整实操
4.1 首次配置时的URL验证流程
当你填写完URL、Token、EncodingAESKey并点击保存时，企业微信服务器会立刻请求你的URL。你可以先写一个简单的接口，打印收到的所有参数，再按照之前的验签逻辑处理。
GET请求的处理步骤是：
- 从Query参数里取
msg_signature、timestamp、nonce、echostr。 - 用
echostr作为encrypt代入验签函数，校验签名。 - 如果签名通过，用
decrypt解密echostr。 - 把解密后的字符串直接作为Response Body返回，响应头
Content-Type可以是text/plain。
这里最常见的坑是：很多人以为要返回加密后的echostr，或者要返回一个特定XML。不是的，URL验证阶段企业微信要求返回的是解密后的明文内容，而不是再加密一遍。我第一次接入时也在这转了半天，后来仔细看了文档才明白。
下面是一段Flask示例：
from flask import Flask, request, Response app = Flask(__name__) callback = WeComCallback(token="your_token", encoding_aes_key="your_aes_key") @app.route("/wecom/callback", methods=["GET", "POST"]) def callback_handler(): if request.method == "GET": msg_signature = request.args.get("msg_signature") timestamp = request.args.get("timestamp") nonce = request.args.get("nonce") echostr = request.args.get("echostr") if not callback.verify_signature(msg_signature, timestamp, nonce, echostr): return "signature error", 403 plaintext = callback.decrypt(echostr) return Response(plaintext, content_type="text/plain") # POST处理在下面补充把这个服务跑起来，用公网可达的URL填入后台，点击保存，正常情况下会提示“保存成功”。如果你的云服务器没有配HTTPS，用HTTP也会被允许，但生产环境我还是建议你在前面加一层Nginx和TLS证书。
4.2 接收文本消息的数据结构与字段含义
配置成功后，用户向应用发消息，你的服务会收到POST请求。此时不要让代码直接对上下文做复杂业务，先把原始body和Query参数打印出来，确认能拿通再去解析业务。
解析方法是：从Query参数里取msg_signature、timestamp、nonce，从POST body里取出<Encrypt>内容，验签后用同一个解密函数解出明文XML。拿到的字段包括：
ToUserName：企业微信的CorpId，可以用来确认消息确实是发给本企业的。FromUserName：发送消息的成员UserID，注意是企业微信内部标识，不是手机号或姓名。CreateTime：消息时间戳，可用于日志排查。MsgType：消息类型，常见text、image、voice、event等。Content：文本消息正文。MsgId：消息唯一ID，用于去重。AgentID：应用ID，如果你一个服务接收多个应用的回调，可以用它来区分。
拿到这些字段后，你就能做业务处理了。比如一个最简单的自动回复：收到“你好”就回复“你好，这里是XX助手”。
4.3 被动回复消息的返回格式
当你的服务处理完消息，如果能在5秒内返回结果，企业微信允许你在当前HTTP响应里直接返回一条加密后的XML作为被动回复。被动回复的XML结构和接收消息类似，但需要自己构造XML后用加密函数处理。
加密函数是解密的逆过程：
def encrypt(self, plaintext): # plaintext是待发送的xml字符串 raw = plaintext.encode("utf-8") pad_len = 32 - (len(raw) % 32) raw = raw + bytes([pad_len]) * pad_len cipher = AES.new(self.aes_key, AES.MODE_CBC, self.iv) encrypted = cipher.encrypt(raw) return base64.b64encode(encrypted).decode("utf-8")然后构造响应XML：
<xml> <Encrypt><![CDATA[加密后的密文]]></Encrypt> <MsgSignature><![CDATA[签名]]></MsgSignature> <TimeStamp>1700000000</TimeStamp> <Nonce><![CDATA[nonce]]></Nonce> </xml>其中MsgSignature的计算方式和验签一样，第四个参数换成加密后的字符串。然后把整个XML作为响应体返回。如果你不打算被动回复，也可以直接返回空字符串或者success，企业微信不会把空响应视为失败。
需要注意的是，5秒是硬限制。如果业务逻辑太慢，比如要查数据库、接第三方接口，很可能超时。我的建议是：超时风险高的功能一律先返回success，同时用异步任务去处理，处理完再调用企业微信的“发送应用消息”接口主动推送结果。这样可以避免用户那边看到“服务异常”之类的提示。
4.4 接收图片、语音、事件等消息的扩展
除了文本，用户还可能发送图片、语音、位置、链接等。它们的解析流程完全一样，只是解密后的XML字段不同。
- 图片消息：
<PicUrl>表示图片URL，<MediaId>表示素材ID。如果要下载图片内容，需要用MediaId调用企业微信素材接口获取二进制。 - 语音消息：
<MediaId>是语音素材ID，企业微信默认不直接给语音转文字，需要额外接入语音识别服务。 - 事件消息：用户进入应用、点击菜单、关注应用等会触发
event类型消息，Event字段会区分enter_agent、click等事件。这类事件通常用于做欢迎语或菜单点击统计。
实际项目里，我一般会先按MsgType做分支，再按业务关键字做路由。这样后续加新类型时只需要扩展，不需要改主流程。
5. 常见问题与排查技巧实录
5.1 URL验证失败的几种典型情况
URL验证失败是最多人卡住的环节。根据我帮别人排查的经验，常见原因有这几类：
- 签名不一致。Token填错了，或者验签时排序写错。比如直接按参数名字母排序，但没有把
encrypt放进去；或者把Token写到了数组外面。 - 响应内容不对。URL验证阶段要求返回解密后的明文，有些代码把
echostr原样返回了，或者返回了密文，后台会提示“回调URL校验失败”。 - 解密失败。EncodingAESKey复制的时候多了空格，或者保存时没有把后台生成的Key完整复制。
- URL不可达。本地开发时用了
localhost或者内网地址，企业微信服务器访问不到。必须用公网地址。如果用内网穿透，穿透服务的免费域名有时会被限制，建议用稳定的穿透方案。 - 响应超时。你的服务被防火墙或安全组拦截，导致企业微信服务器请求超时。
排查方法是：先在代码里把收到的请求参数和验签、解密过程打日志，然后手动用后台的“保存”按钮触发一次，看日志里到底哪一步失败。只要日志打清楚，问题基本能定位。
5.2 收不到消息或消息乱码
配置保存成功，但给应用发消息后，服务器没收到POST请求。这种情况先检查三件事：
第一，应用是否发布。自建应用保存后默认是“未发布”状态，只有企业管理员和可见范围内的开发者能在企业微信客户端看到。你要在后台点“发布”，或者用测试企业的“体验成员”身份测试。
第二，用户是否在可见范围内。如果用户不在应用可见范围，他就看不到这个应用，自然发不了消息。去后台把成员或部门加到可见范围。
第三，回调服务是否正常运行。你可以在服务器上手动curl模拟POST，确认服务能正常响应。另外检查企业微信后台“接收消息”是否处于“已开启”状态。
消息乱码通常是解密后没有正确按UTF-8解码，或者解密函数没有正确去掉PKCS#7填充。还有可能是你在解析XML时用了错误的编码，比如把GBK当成UTF-8。统一用UTF-8就不会有这种问题。
5.3 被动回复超时与重试机制
企业微信对被动回复有5秒限制。如果你的服务在5秒内没有返回结果，企业微信会认为本次回调失败，可能触发重试。重试会导致用户发送一条消息，你的服务收到多次相同MsgId的消息。
所以，消息处理一定要做幂等。不管你业务逻辑怎么设计，至少要在入库或者调用第三方接口前，用MsgId做去重。简单做法是在Redis里存一下MsgId，设置几小时的过期时间，重复消息直接丢弃。
如果业务逻辑确实慢，我建议的架构是：收到消息后，立刻返回success，把消息内容扔到消息队列（比如Redis List或RabbitMQ）里，后台Worker异步处理，再调用主动发送消息API返回结果。这样既不超时，又能保证体验。
5.4 安全边界与合规建议
最后强调一下安全。API接收消息意味着你的服务器会拿到用户真实发给应用的文本、图片等数据。这些数据可能包含内部业务信息，甚至个人信息。至少要做好几件事：
- 传输层加密。生产环境必须使用HTTPS，不要让回调明文跑在HTTP上。
- 验签不能省。每次请求都要校验
msg_signature，防止伪造消息。 - 敏感数据脱敏。日志里不要把完整消息正文打出来，尤其是涉及账号、手机号的内容。
- 数据保留策略。如果业务不需要长期留存消息，处理完就删除，降低泄露风险。
- 权限最小化。应用权限只要能完成业务就好，不要申请不必要的接口权限。
我在实际项目里就遇到过有人直接把用户消息原文打到日志里，结果日志被同步到第三方存储，由此牵出一堆隐私合规问题。这种问题一旦发生非常麻烦，接入之初就按规范来，比事后补救成本低得多。
最后再分享一个小技巧：第一次接入时，不要急着写复杂业务。先把“接收消息-解密-原样回复带内容”这个最小闭环跑通，再一步一步加规则、加数据库、加异步任务。这个项目我前前后后做过好几个企业对接，最深的体会是：企业微信回调这块，90%的问题出在配置细节和签名算法上，代码本身反而没那么复杂。把上面这些点提前避开，你就能少走很多弯路。
