最近做的企微二开机器人要支持发图片、文件、富文本卡片。之前只做文本消息做完发现富媒体消息的处理和文本完全不同——接收要下载、发送要构造、存储要管理、兼容性要考虑。把踩过的坑记下来。底层用的是Eyun 平台开放的企微 API承接消息收发和文件管理本文重点不在调接口在富媒体消息怎么接收、处理、发送。接收图片不只是下载客户发图片机器人要能看懂。接收流程拿到图片消息回调带 fileId调 CDN 接口下载图片到本地或 OSSOCR 识别图片文字如果是截图多模态模型理解图片内容如果是实物照片把理解结果作为文本存入消息上下文def handle_image_message(msg): file_path cdn_api.download(msg.file_id, save_tooss) 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 上传两步走、存储引用分离、客户端兼容降级这些工程细节。每一项都不深奥但少做一项富媒体消息就跑不稳。这套搭扎实机器人真正能收发图片文件富文本——而不是只会发文字的半成品。