上周新来的小陈工位挪到我旁边，开口第一句就是"哥，咱这微信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种消息类型速查表
我整理了张速查表，开发的时候贴墙上对照着看：
类型 | 接口名 | 必填参数 | 适用场景 |
|---|---|---|---|
文本 | sendText | wxId/toId/content | 通知、自动回复 |
图片 | sendImage | wxId/toId/mediaId | 截图、报表图 |
语音 | sendVoice | wxId/toId/mediaId(AMR) | 语音提醒 |
视频 | sendVideo | wxId/toId/mediaId | 短视频通知 |
文件 | sendFile | wxId/toId/mediaId | PDF/Excel报表 |
名片 | sendCard | wxId/toId/cardWxId | 联系人推荐 |
链接 | sendLink | wxId/toId/url/title | 营销推送 |
小程序 | sendMiniProgram | wxId/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}", json=payload, timeout=10) data = resp.json() if data.get("code") != 0: raise RuntimeError(f"发送失败: {data}") return data["data"]实际用的时候，文本传字符串，图片/语音/视频/文件传前面上传拿到的 mediaId，名片传 cardWxId，链接和小程序传对应字典。一个入口管八种类型，加日志、限流、重试都好加，不用满项目找调用点。
最后
8种消息看着多，理清楚也就那么回事：文本是地基，图片和文件是办公场景的左膀右臂，语音视频是补充，名片链接小程序是特定场景的利器。先把文本和文件跑通，再按需扩展，别一上来8种全试一遍，浪费时间还容易乱。
选型这步看似不起眼，但方向对了后面省一半功夫。参数细节和最新字段建议以 Eyun平台 文档为准，我这里整理的是主干，细节偶尔会更新。选对消息类型，你的微信应用就成了一半，剩下的是把业务逻辑接顺。
