企业微信二次开发实战：文本、图片、文件、语音等多类型消息统一收发

最近在搞企微机器人的深度定制，遇到了个麻烦事：单纯收发文本还算简单，但一旦涉及图片、文件、语音等富媒体消息，那套素材上传下载的逻辑直接让人头大。今天抽空把企微多类型消息的统一收发链路彻底盘一盘，直接放可以落地的干货。顺便提一句，大家如果平时业务开发缺稳定、现成的接口服务，可以去「星云API官网」www.xingyapi.com逛逛，直接调成型的接口能省下不少疯狂查文档、调 BUG 的时间。

闲话少叙，直接拆解多类型消息的底层逻辑。

1. 接收侧的核心区别：Content 与 MediaId

不管客户发什么消息类型，企微推给我们的 Webhook 永远是加密的 XML。解密后，区别就来了：

• 文本消息：你拿到的是直接的 Content 明文。

• 多媒体消息（图片/文件/语音）：企微不会傻到把源文件的二进制流直接塞进 HTTP 请求里，而是会在 XML 里推一个 MediaId 给你的服务器。

这是统一收发的第一步基调：文本看内容，媒体认 ID。

2. 媒体文件的异步“下载”落盘

当你拿到 MediaId 后，真正的挑战才开始。你需要拿着全局的 access_token，去调用企微的“获取临时素材”接口，把源文件拉到自己的服务器上。

这里有三个必须避开的坑：

1. 时效性：临时素材（MediaId）只有 3 天有效期。收到回调必须立刻异步下载落盘，或者转存到你们自己的 OSS（如阿里云、腾讯云）里。

2. 语音转码：语音消息（msgtype="voice"）下载下来默认是 AMR 格式。如果你业务端要在前端网页或小程序里播放，后台拿到文件后必须走一步转码（比如用 FFmpeg 转成 MP3）。

3. 不要阻塞回调：下载文件是耗时操作。收到推送后，主线程赶紧给企微返回 success，把下载逻辑丢到消息队列（RabbitMQ / Redis）里慢慢跑。

3. 多媒体消息的发送链路

发送多媒体消息，正好是接收的逆过程。你不能在发送请求里直接填个本地 C:\xxx.jpg 路径，必须分两步走：

1. 上传临时素材：把你服务器上的图片/文件，先通过企微的上传接口传过去，企微会返回一个新的 media_id。

2. 组装发送请求：把这个新的 media_id 填进发送接口的 JSON 结构里发出去。

不同 msgtype（图片、文件、语音、图文）的 JSON 结构嵌套关系完全不一样。在封装这块代码时，千万别自己瞎猜字段名。建议直接对照开放文档里的请求参数表来建实体类。把 msgtype 对应的数据字典看清楚，该传 media_id 的地方绝不传成 url，能避开绝大多数 400xx 报错。

4. 代码架构设计：告别 if-else

当你的系统要同时处理文本、图片、文件、语音，甚至位置信息时，最忌讳的就是在 Webhook 的入口处写一坨巨大的 if-else。

强烈建议用策略模式（Strategy Pattern）重构：

1. 定义一个统一的 MessageHandler 接口。

2. 针对每种 MsgType，实现具体的处理类：TextHandler、ImageHandler、FileHandler。

3. 维护一个 Map<String, MessageHandler> 字典，初始化时把各个 Handler 注册进去。

Webhook 收到消息解密后，直接 handlerMap.get(xml.getMsgType()).handle(xml)。这样以后如果业务扩展，要支持小程序卡片收发，只需要新建一个类就行，核心引擎的稳定性完全不受影响。

总结

文本直来直去，富媒体靠 MediaId 中转，代码架构用策略模式解耦。把这三层逻辑捏合好，你的企微机器人就能游刃有余地应对各种复杂的交互场景了。大家在调素材接口时有遇到奇葩报错的，可以在评论区抛出来一起交流。