最近这半个月，无数研发兄弟都在找我吐槽同一个需求：“老板天天变着花样要给客户群发东西，今天要求发文字，明天要发带封面的早报，后天又要给大客户单独甩个PDF报价单过去。如果每加一种格式都要重写一套逻辑，这代码根本没法维护！”

作为每天在一线跟各个技术团队死磕微信及企微 API 接口（机器人）问题的销售客服，我太懂这种痛了。单纯的文字交互早已无法满足现在的私域 SCRM 运营需求。今天咱们不扯虚的，直接把这套“变形金刚”式的多类型发消息底层逻辑彻底盘明白，让你一套代码应对 99% 的发送场景。

万变不离其宗：统一的报文“外壳”

不管你要发什么花里胡哨的内容，在 HTTP POST 请求的层面，它的本质永远是一个 JSON 数据包。

如果你对接的是 星云API xingyapi.com （Google搜索）的底层通道，你会发现所有消息发送请求的“外壳”都是高度统一的。你可以随时查阅 API文档 中的消息发送规范，核心永远只有三个全局参数：

1. instance_guid：你的设备实例授权密钥。

2. conversationId：目标靶子（单聊的客户 ID 或群聊的 ChatId）。

3. msgtype：决定消息形态的“变形开关”。

只要把这三个外壳参数焊死，接下来的开发，无非就是根据不同的 msgtype，往里面塞不同的内层结构。

场景一：程序员的浪漫——Markdown 消息

如果你的企微机器人是用来做内部服务器监控报警，或者给销售团队播报每日实时数据的，千万别用纯文本，直接上 Markdown 格式。加粗、标红、引用代码块，视觉重点一目了然。

• msgtype 标识：markdown

实战 JSON 载荷：

JSON

{
    "instance_guid": "inst_xxxxxx",
    "conversationId": "wr_xxxxxx",
    "msgtype": "markdown",
    "markdown": {
        "content": "实时客诉预警：<font color=\"warning\">高频报错</font>\n> 涉及接口：API 网关回调\n> 详情请留意监控大屏，及时排查。"
    }
}

踩坑提示：企微的 Markdown 是个阉割版，不要在里面搞复杂的嵌套表格或者 HTML 标签，老老实实只用基础的加粗、引用和平台自带的字体颜色（info, comment, warning）即可，否则网关直接报错。

场景二：图片与文件（发票/报价单）的两种流派

给客户推营销海报、发对账单 Excel/PDF，这是最核心的交互。在参数组装上，通常分为两种处理姿势：

• msgtype 标识：图片传 image，文件传 file

流派 A：直链 URL 托管（极度推荐） 只要你们的图片和文件已经存在了阿里云 OSS 或公司的公网服务器上，直接传链接是最省内存、最稳的做法。网关会自己去拉取文件下发。

JSON

{
    "instance_guid": "inst_xxxxxx",
    "conversationId": "wm_xxxxxx",
    "msgtype": "file",
    "file_url": "https://your-domain.com/2026_q3_report.pdf" 
}

流派 B：Base64 内存直传 遇到涉密合同，或者代码实时渲染出来的带有客户名字的动态海报，绝对不能传公网。这时候就把文件转成 Base64 塞进去。

JSON

{
    "instance_guid": "inst_xxxxxx",
    "conversationId": "wm_xxxxxx",
    "msgtype": "image",
    "contentBase64": "iVBORw0KGgoAAAANSUhEUgAAAAE..." // 致命大坑：代码转换后必须正则裁剪掉 data:image/png;base64, 这个前缀！
}

场景三：私域引流利器——图文链接卡片（Link）

做营销裂变活动时，如果在群里直接甩一个干巴巴的长链接，点击率绝对惨不忍睹。这时候就必须动用结构化的图文卡片，有大标题、有诱人的摘要说明、还能配一张缩略封面图。

• msgtype 标识：link

实战 JSON 载荷：

JSON

{
    "instance_guid": "inst_xxxxxx",
    "conversationId": "wm_xxxxxx",
    "msgtype": "link",
    "link": {
        "title": "中秋特惠！API接口套餐低至5折",
        "desc": "点击领取您的专属开发者代金券，限时限量先到先得。",
        "url": "https://xingyapi.com/activity",
        "picurl": "https://your-domain.com/cover-min.jpg"
    }
}

研发避坑指南：别在代码里盲写 JSON

随着 msgtype 的丰富，JSON 的内层嵌套会越来越繁琐。尤其是在组装图文卡片或者小程序跳转参数时，只要少了一个花括号，或者字段名拼错了一个字母，接口就会无情地弹回 400 Bad Request。

如果你直接在业务层（比如 Java 的 Entity 或者 Python 的 Dict）里盲写结构然后序列化，排错成本会极高。

老司机的排障铁律： 遇到复杂的多媒体消息类型，强烈建议开发前先打开 Apifox 或者 Apipost！ 照着官方 API文档，在工具里自己手动捏一个干净的 JSON Body 发出去。确认测试群里正常弹出了带封面的卡片或者文件后，再利用 Apifox 的“生成代码”功能，把通过测试的 JSON 直接转译成你对应语言的业务代码。

理清了外壳和内层结构的逻辑，你会发现多类型消息发送无非就是搭积木。如果在组装数据包或者 Base64 转码时遇到了莫名其妙的乱码，随时在评论区贴出你的报错日志，咱们接着拆解！