一、核心 API 接口与请求结构

实现向外部群（客户群）发送消息的核心接口是：

• API 接口： POST /cgi-bin/appchat/send

• 用途： 应用向群聊发送消息。

• 身份： 消息以应用的身份发送。

• 请求主体 (Payload) 结构： 必须是 JSON 格式。

1.1 基础 JSON Payload 结构

所有发送给群聊的消息 JSON 必须包含以下基础字段：

字段名	类型	描述
chatid	string	目标群聊的 ID。
msgtype	string	消息类型，如 text、image、file、link 等。
safe	int	是否是保密消息，0 (否) 或 1 (是)。建议保持 0。
消息内容对象	object	根据 msgtype 命名的对象，包含消息的具体内容。

---

二、Payload 构造详解：主流消息类型

根据 msgtype 的不同，消息的具体内容对象（如 text, image, link）的结构也不同。

2.1 文本消息 (msgtype: "text")

这是最简单也是最常用的消息类型。

字段名	类型	描述
text.content	string	消息文本。支持 2048 字节，超过会被截断。

JSON 示例 (文本消息):

JSON

{
    "chatid": "wrU123456789",
    "msgtype": "text",
    "text": {
        "content": "📢 尊敬的客户，本周特惠产品已更新，请点击链接查看详情！"
    }
}

---

2.2 图片消息 (msgtype: "image")

用于发送图片。消息主体中不能直接发送图片文件，必须提供一个已上传至企业微信的 媒体 ID。

字段名	类型	描述
image.media_id	string	图片的临时素材 ID。必须通过媒体上传接口事先获取。

JSON 示例 (图片消息):

{
    "chatid": "wrU123456789",
    "msgtype": "image",
    "image": {
        "media_id": "3M0uW32r2_P6_v4V04_X5u6F7I8T9N0K1L2J3H4G5F6E"
    }
}

---

2.3 文件消息 (msgtype: "file")

用于发送 PDF、Excel 等文件。与图片消息类似，需要提供 媒体 ID。

字段名	类型	描述
file.media_id	string	文件的临时素材 ID。通过媒体上传接口获取。

JSON 示例 (文件消息):

{
    "chatid": "wrU123456789",
    "msgtype": "file",
    "file": {
        "media_id": "1V3uW12r2_P6_v4V04_X5u6F7I8T9N0K1L2J3H4G5F6E"
    }
}

---

2.4 图文链接卡片消息 (msgtype: "link")

用于发送带有标题、描述和封面的外部链接，以卡片形式展示。

字段名	类型	描述
link.title	string	链接标题（必填）。
link.text	string	链接描述。
link.picurl	string	封面图片 URL。
link.messageurl	string	点击后跳转的 URL（必填）。

JSON 示例 (链接卡片):

{
    "chatid": "wrU123456789",
    "msgtype": "link",
    "link": {
        "title": "🎉 2024 年终大促活动详情",
        "text": "点击查看所有产品的折扣力度和限时抢购时间表。",
        "picurl": "http://example.com/cover_image.jpg",
        "messageurl": "http://example.com/sale_details"
    }
}

---

三、Payload 构造的注意事项

1. 媒体 ID 的时效性： 图片和文件使用的 media_id 有效期为 3 天（72 小时）。必须在有效期内使用。如果 ID 过期，需要重新上传获取新的 ID。

2. JSON 编码： 整个 Payload 必须进行正确的 JSON 编码。任何特殊字符（如换行符、引号）必须被转义。

3. URL 编码： 在链接卡片中，messageurl 字段的 URL 需确保已进行 URL 编码，以防包含特殊字符。

4. 字段校验： 严格遵循企业微信 API 文档中对每个字段的长度和格式要求，缺失必填字段或字段格式错误会导致 API 返回错误。例如，文本内容不能超过 2048 字节。

​

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

操作步骤

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

目的

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