上周新来的小陈工位挪到我旁边开口第一句就是哥咱这微信API能发啥消息啊文档我翻了半天还是没整明白。我当时正改一个bug随口回了句自己看文档去但看他一脸懵的样子想起我三年前刚接这块也是一样——8种消息类型散在文档各处谁配合谁、什么场景用什么没人串一下是真摸不着头脑。那天下班我没急着走把 Eyun开发文档 翻了一遍整理出一份能直接对照着写的清单给他。今天顺手整理成文章给同样卡在选型阶段的朋友省点时间。一、8种消息类型逐一过一遍1. 文本消息sendText最常用没有之一。发通知、做自动回复、推系统告警80%的场景都是它。参数要点wxId发送方实例、toId接收方、content文本内容就这三个核心字段。踩坑点文本长度有上限超过会被截断。我之前给客户推一段长报错日志结果只收到一半排查半天才知道是超长了。长内容建议拆条发或者干脆改用文件消息。2. 图片消息sendImage发截图、发报表图、发验证码凡是图都用它。参数要点先调上传接口拿mediaId也有文档叫 fileId再拿这个 id 调 sendImage。两步走别想着一步到位。踩坑点第一次接我直接把图片 base64 塞进发送接口报错报得我怀疑人生。后来才看清要先上传。图片格式支持 jpg/png体积别太大不然上传慢还容易被风控盯上。3. 语音消息sendVoice发语音提醒适合开车场景或者长内容不想让用户盯着字看的。参数要点跟图片类似先上传拿mediaId。格式必须是 AMR其他格式不行。踩坑点我用录音接口出来的不是 AMR调接口一直失败最后用 ffmpeg 转了一道才通。格式这关卡了我小半天文档里其实写了我当时没细看。4. 视频消息sendVideo发短视频通知比如监控告警配个现场画面、产品演示片段。参数要点先上传视频拿mediaId再调 sendVideo。视频时长和体积都有建议范围文档里有标。踩坑点视频太长会被拒我传过 50MB 的视频直接超限。后来压缩到 10MB 以内才稳。短视频通知嘛别整大片又慢又占带宽。5. 文件消息sendFile发 PDF、Excel、Word 报表办公场景的命根子。参数要点同样是先上传拿mediaId再调 sendFile。支持常见文档格式。踩坑点这个我推荐办公场景优先用它别用图片消息发报表截图——截图看不清数字还得让客户放大。我做过一个月报表推送从截图改成文件客户反馈直接好评。6. 名片消息sendCard发联系人名片A 推 B 给 C 的场景。参数要点参数里带的就是被推荐人的wxId和昵称。踩坑点被推荐的人必须是你好友不然发出去点不开。我踩过这个坑名片发出去了客户点了没反应查了半天才知道那人早删了我。7. 链接消息sendLink发图文链接卡片标题摘要缩略图链接营销推送的主力。参数要点标题、描述、缩略图URL、跳转URL几个字段填齐。踩坑点缩略图建议用小图加载快。我之前用 2MB 的大图当缩略图卡片加载慢吞吞的用户以为卡了直接划走。这块的具体字段说明建议在 Eyun平台 看最新版本参数偶尔会微调。8. 小程序消息sendMiniProgram发小程序卡片电商导购、小程序商城场景的标配。参数要点小程序的 appId、页面路径、标题、缩略图。踩坑点小程序必须和当前微信号有授权关系否则发不出去。这个我没踩过但群里有人问过提前说一句避坑。二、5个典型使用场景光知道有8种消息不够得知道什么场景用什么。我把做过的项目归了5类1. 通知推送系统状态变了推给用户知道。文本就够复杂场景配图片。比如订单发货通知用 sendText配个物流单号截图用 sendImage。我做的工单系统告警就是纯文本简单粗暴但好用。2. 客服回复用户问啥答啥。90% 用 sendText遇到要发资料就上 sendFile。客服场景文本响应最快别为了花哨用图片用户等的是答案不是图。3. 报表发送定时给管理层推数据。Excel 用 sendFile数据图表用 sendImage。我现在做的日报系统就是这两个轮着用早上8点自动推到管理群。4. 营销推送活动推广。sendLink 出场率最高图文卡片点击率高。但别滥用频率控制前面提过我吃过被举报拉黑的亏。5. 电商导购商品推荐。sendMiniProgram 引导到小程序下单闭环最顺。也有用 sendLink 跳 H5 的看业务形态能走小程序就别走 H5体验差一截。三、8种消息类型速查表我整理了张速查表开发的时候贴墙上对照着看类型接口名必填参数适用场景文本sendTextwxId/toId/content通知、自动回复图片sendImagewxId/toId/mediaId截图、报表图语音sendVoicewxId/toId/mediaId(AMR)语音提醒视频sendVideowxId/toId/mediaId短视频通知文件sendFilewxId/toId/mediaIdPDF/Excel报表名片sendCardwxId/toId/cardWxId联系人推荐链接sendLinkwxId/toId/url/title营销推送小程序sendMiniProgramwxId/toId/appId/path电商导购这张表是我做完几个项目复盘出来的新人按这个选型能少走弯路。参数细节偶尔有更新建议接之前对照 Eyun开发文档 确认下别照老记忆写。四、一个统一发送方法8种消息接口名不一样但参数结构大同小异。我项目里用一个统一方法收口传msgType切换类型维护起来轻松不少import requests BASE_URL https://api.eyunz.com # 以文档实际地址为准 def send_message(wx_id, to_id, msg_type, content): 统一发送各类消息 msg_type: text/image/voice/video/file/card/link/miniapp content: 文本为字符串其余为mediaId或字典 api_map { text: sendText, image: sendImage, voice: sendVoice, video: sendVideo, file: sendFile, card: sendCard, link: sendLink, miniapp: sendMiniProgram } api api_map.get(msg_type) if not api: raise ValueError(f不支持的消息类型: {msg_type}) payload {wxId: wx_id, toId: to_id, msgType: msg_type, content: content} resp requests.post(f{BASE_URL}/{api}, jsonpayload, timeout10) data resp.json() if data.get(code) ! 0: raise RuntimeError(f发送失败: {data}) return data[data]实际用的时候文本传字符串图片/语音/视频/文件传前面上传拿到的 mediaId名片传 cardWxId链接和小程序传对应字典。一个入口管八种类型加日志、限流、重试都好加不用满项目找调用点。最后8种消息看着多理清楚也就那么回事文本是地基图片和文件是办公场景的左膀右臂语音视频是补充名片链接小程序是特定场景的利器。先把文本和文件跑通再按需扩展别一上来8种全试一遍浪费时间还容易乱。选型这步看似不起眼但方向对了后面省一半功夫。参数细节和最新字段建议以 Eyun平台 文档为准我这里整理的是主干细节偶尔会更新。选对消息类型你的微信应用就成了一半剩下的是把业务逻辑接顺。