复杂消息格式自动化：图片、视频和自定义卡片的消息体构造

摘要

企业微信外部群的自动化应用场景远超纯文本消息。实现图片、视频和自定义卡片 等复杂消息格式的推送，要求自动化系统深入理解非官方 API 对这些媒体文件的特殊处理机制------即媒体文件上传 和 media_id 的依赖 。本文将详细拆解复杂消息的数据结构、文件上传流程 ，以及在 RPA 模拟和 API 调用中，如何实现消息体的精确构造和编码。

---

一、 复杂消息推送的核心机制：Media ID

无论是图片、视频还是文件，都不能直接将二进制数据塞入消息请求体中。平台要求先上传文件，获取一个临时的唯一标识符------媒体 ID (media_id)。

1. 文件上传的流程

文件上传是一个独立于消息发送的 API 调用流程：

1. 准备文件： 确定本地文件路径，并获取文件的 MIME 类型（例如，image/jpeg，video/mp4）。

2. 上传 API 调用： 自动化 Worker 调用特定的文件上传接口（不同于消息发送接口），将文件数据作为请求体发送。

3. 获取 Media ID： 上传成功后，服务器返回一个 JSON 响应，其中包含临时的 media_id 和有效期（通常为几天）。

4. 存储与复用： 自动化系统应将 media_id 及其过期时间存储在缓存中。在有效期内，后续的消息推送可直接复用该 ID，避免重复上传。

2. RPA 在文件上传中的角色

在缺乏直接上传 API 或需要处理特殊鉴权时，RPA 可作为上传的兜底：

• RPA 模拟上传： RPA 模拟打开文件选择对话框，输入本地路径，完成文件上传。RPA 再通过网络嗅探 或日志分析 捕获上传成功后客户端生成的 media_id。

• 兼容性挑战： RPA 必须能处理不同操作系统的文件选择器 UI，这是复杂消息推送中的常见故障点。

---

二、 复杂消息格式的 JSON 构造与解析

获取 media_id 后，消息发送 API 的请求体结构会根据消息类型发生变化。

1. 图片与视频消息 (Type: image, video)

这类消息的核心是引用 media_id。

• 图片消息 JSON 模板：

  {
      "msgtype": "image",
      "image": {
          "media_id": "YOUR_UPLOADED_MEDIA_ID" 
      }
  }

• 视频消息 JSON 模板： 视频可能需要额外的字段如时长等。

  {
      "msgtype": "video",
      "video": {
          "media_id": "YOUR_UPLOADED_MEDIA_ID",
          "thumb_media_id": "THUMBNAIL_MEDIA_ID" // 可能需要缩略图ID
      }
  }

• 挑战： 视频消息可能要求同时上传 视频文件本身和其缩略图文件 ，即需要获取两个不同的 media_id。

2. 自定义链接卡片（Structured Card）

链接卡片（或其他结构化消息）不依赖 media_id，但要求精确的字段结构。

• 核心字段： title (标题)、description (描述/摘要)、url (点击跳转链接) 和 picurl (缩略图 URL)。

• JSON 模板示例：

  {
      "msgtype": "link",
      "link": {
          "title": "最新活动公告",
          "text": "点击查看本周独家优惠详情。",
          "message_url": "https://your.company.com/promo",
          "picurl": "https://your.company.com/promo/thumb.png" 
      }
  }

• 数据填充： 自动化系统需要从业务数据库（如 CMS）中拉取这些字段，进行安全编码（如 URL Encoding）后填入 JSON 模板。

---

三、 流程控制：串行化与容错

复杂消息的发送流程是串行的，不能并行执行。

• 串行依赖： 任务流程必须严格遵循：[上传文件] \\rightarrow [获取 ID] \\rightarrow [发送消息]。任何一步失败，流程必须中断或转入容错机制。

• 容错机制：

  1. 上传失败： 如果文件上传失败（如网络错误），记录错误，并触发重试策略。

  2. Media ID 过期： 如果缓存中的 media_id 已过期，系统应强制重新执行上传流程，而不是直接尝试发送。

  3. 发送失败： 如果发送消息失败，但不影响 media_id 的有效性，则记录失败并用纯文本消息作为降级方案进行发送。

---

四、 总结

企业微信外部群的复杂消息格式自动化，是一项依赖于文件上传前置 API 和精确 JSON 构造 的技术。核心技术壁垒在于对 media_id 机制的理解和高效管理。只有构建出稳定可靠的媒体文件上传和 ID 缓存流程，才能确保自动化系统能够以丰富的多媒体形式，支撑企业精细化的运营和营销需求。

---

​

实施建议：客户联系功能启用步骤

操作步骤

1. 权限申请
   请通过 QiWe开放平台管理后台，提交"客户联系"功能的使用权限申请。
2. 获取访问凭证
   请使用企业 corpidcor pid （企业ID）和 corpsecretcorpsecret （应用密钥）作为参数，调用相应接口以获取 access_tokenaccess _token （访问令牌）。

目的

完成上述轻量级开发部署后，即可启用通过接口进行客户联系管理的能力。