最近做的企微二开，机器人要支持发图片、文件、富文本卡片。之前只做文本消息，做完发现富媒体消息的处理和文本完全不同——接收要下载、发送要构造、存储要管理、兼容性要考虑。把踩过的坑记下来。
底层用的是Eyun 平台开放的企微 API，承接消息收发和文件管理，本文重点不在调接口，在"富媒体消息怎么接收、处理、发送"。
接收图片：不只是下载
客户发图片，机器人要能"看懂"。接收流程：
拿到图片消息回调（带 fileId）
调 CDN 接口下载图片到本地或 OSS
OCR 识别图片文字（如果是截图）
多模态模型理解图片内容（如果是实物照片）
把理解结果作为文本存入消息上下文
def handle_image_message(msg): file_path = cdn_api.download(msg.file_id, save_to="oss") if is_screenshot(file_path): text = ocr_engine.recognize(file_path) return {"type": "image_screenshot", "text": text} else: description = vision_model.describe(file_path) return {"type": "image_photo", "description": description}关键坑：图片下载要异步，不能阻塞回调；OCR 和视觉理解要超时控制，模型慢了回调就超时。下载完存 OSS，本地不留文件，不然磁盘爆。
接收文件：类型识别和存储
客户发文件，机器人要识别是什么文件：
文档类（PDF/Word/Excel）：存 OSS，提取文本进知识库
图片类：走图片处理流程
压缩包：解压后按文件类型分别处理
其他：存 OSS，记录元数据
文件消息的处理比图片重——文件可能大，下载慢，处理更耗时。所有处理走异步队列，机器人先回"收到文件，处理中"，处理完再回复结果。同步处理，回调必超时。关于文件下载和存储接口，可以看Eyun 开发文档。
发送富媒体：图文消息构造
发富媒体不是简单调个 sendImage，要构造完整的富媒体消息：
图片消息：直接发图片
图文消息：标题 + 描述 + 图片 + 链接
文件消息：发文件
富文本卡片：按钮 + 内容 + 跳转
图文消息的坑是图片要先上传 CDN 拿 mediaId，再用 mediaId 发送。两步走，不是直接发图片 URL：
发送流程: 1. 上传图片到CDN → 拿到 media_id 2. 用 media_id 构造图文消息 3. 调发送接口media_id 有有效期（通常是几天），过期的要重新上传。我们最早缓存 media_id 用了一周，结果过期发不出去，客户没收到，排查半天。
富媒体的存储和引用
富媒体消息的存储和文本不同：
媒体文件存 OSS，不存数据库
数据库存引用（OSS 路径、mediaId、文件类型）
消息归一化时把图片/文件转成文本描述（"图片：[截图内容]"）
这样 AI 处理消息时不用真的拉图片，读文本描述就行。需要看原图时按引用从 OSS 拉。这套不做，AI 处理富媒体消息全靠猜。
富媒体消息的兼容性
不同端对富媒体的支持不一样：
企微客户端：全支持
微信客户端（外部客户）：部分支持，某些卡片不显示
低版本客户端：只支持基础消息
发送富媒体要做降级——检测客户端能力，不支持的降级成文本消息。不做降级，外部客户在微信里看到"收到一条不支持的卡片消息"，体验极差。关于富媒体消息格式和兼容性，在Eyun 企业微信 API 平台开通后可以测试不同端的兼容情况。
写在最后
富媒体消息这套东西，难点不在调发送接口，在图片 OCR、文件类型识别、CDN 上传两步走、存储引用分离、客户端兼容降级这些工程细节。每一项都不深奥，但少做一项富媒体消息就跑不稳。这套搭扎实，机器人真正能收发图片文件富文本——而不是只会发文字的半成品。
