企业微信API接口开发：外部联系人-群聊消息群发设计

文档基础信息

1 整体业务架构与核心概念

1.1 分层架构

1. 实例管理层：企微 iPad 账号初始化、代理配置、登录 / 登出、多实例查询，生成全局唯一 uuid；

1. 素材上传层：CDN 小文件、大文件分片上传，输出 cdnkey/aeskey/md5 等消息发送必备参数；

1. 收件人拉取层：分页查询外部联系人、内部成员、客户群、内部群 ID，提供群发 vids 数组；

1. 消息发送层：分为单发接口、群发接口SendGroupsMsg，群发底层复用全部单发消息能力，仅支持批量接收人；

1. 消息回调层：HTTP/RabbitMQ 两种推送方式，接收发送回执、客户回复、群消息、离线消息；

1. 辅助工具层：群管理、标签管理、文件下载、id 互转工具接口。

1.2 核心字段释义

1.3 群发核心逻辑说明

1. SendGroupsMsg无单人 / 群每日发送次数限制，不存在每人每日一条的约束；

1. 群发本质为批量调用单发逻辑，支持一次性传入多个联系人 / 群 ID，批量推送同一条组合消息；

1. 支持批量纯联系人、批量纯群，禁止联系人与 roomid 混合传入 vids 数组；

1. 支持文本、图文、文件、视频、链接卡片、小程序、视频号等所有消息类型自由组合群发。

2 全局统一接口返回规范

所有 JSON 请求接口统一返回结构：

{ "data": {}, "errcode": 0, "errmsg": "ok" }

• errcode=0：请求成功，data 承载业务数据；

• errcode≠0：请求异常，errmsg 携带错误描述；

• 高频报错：errcode:500,errmsg:"uuid参数不存在"，代表请求 JSON 内缺少 uuid 字段。

3 账号实例生命周期接口

3.1 初始化 /wxwork/init

功能

创建 iPad 企微实例，生成 uuid，支持代理配置、历史账号自动登录绑定 vid。

请求参数

| 参数 | 类型 | 是否必传 | 说明 |
| ---- | ---- | ---- |
| vid | string | 否 | 首次初始化填空；已登录账号传 16888 开头账号 id，用于自动登录 |
| ip/port/proxyType | string | 否 | 代理服务器信息，无代理不传 |
| userName/passward | string | 否 | 代理账号密码，无则忽略 |
| proxySituation | int | 否 | 1 = 全局代理（永久生效，无法取消）；0 = 临时代理，可动态取消 |
| deverType | string | 是 | 固定值ipad|

无代理初始化请求示例：

{ "vid": "", "ip": "", "port": "", "proxyType": "", "proxySituation": 0, "deverType": "ipad" }

返回示例：

{ "data": { "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e71a1e", "is_login": "false" }, "errcode": 0, "errmsg": "ok" }

3.2 设置消息回调地址 /wxwork/SetCallbackUrl

两种推送模式

1. HTTP 回调（推荐）：自建服务接收 POST 推送；

1. RabbitMQ 回调：交换机 + 路由键推送消息。

HTTP 请求示例

{ "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e71a1e", "url": "http://127.0.0.1:8084/wxwork/callback" }

回调推送数据格式

{ "uuid": "实例uuid", "json": "原始消息完整JSON字符串", "type": "消息类型编码" }

回调服务返回要求

必须同步返回{"errcode":0,"errmsg":"ok"}，否则服务重复推送消息。
Java 标准回调示例：

java @PostMapping("/wxwork/callback") @ResponseBody public Map<String,String> callback(@RequestBody JSONObject json) { System.out.println("实例ID：" + json.get("uuid")); System.out.println("原始消息：" + json.get("json")); Map<String,String> result = new HashMap<>(); result.put("errcode", "0"); result.put("errmsg", "ok"); return result; }

3.3 登录全系列接口

1. 获取登录二维码/wxwork/getQrCode
   入参仅 uuid，返回二维码访问链接 + base64 图片；

1. 验证码校验/wxwork/CheckCode
   首次扫码弹窗验证码时调用，报错qrcode_not need verify代表不要提前关闭手机验证码弹窗；

1. 自动登录/wxwork/automaticLogin
   初始化传入有效 vid 时免扫码登录；

1. 退出登录/wxwork/LoginOut：登出当前实例会话。

3.4 实例管理辅助接口

1. /wxwork/GetRunClient：查询所有在线企微实例；

1. /wxwork/GetRunClientByUuid：根据 uuid 查询账号登录状态、个人信息；

1. /wxwork/CloseConnent：销毁实例连接；

1. /wxwork/setProxy：动态设置 / 取消临时代理（proxySituation=0 生效）。

3.5 离线消息同步 /wxwork/SyncAllData

登录完成后调用，拉取离线期间未接收消息，避免群发上下文缺失。
请求示例：

{ "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e71a1e", "limit": 1000, "seq": 12481627 }

返回is_select=1代表仍有离线消息，循环分页拉取。

4 素材上传模块（群发前置依赖）

群发中图片、文件、视频、小程序封面等多媒体内容，必须先上传获取全套参数，填入msg_list数组。

4.1 CDN 图片上传（≤25MB）

• 本地文件：/wxwork/CdnUploadImg，请求格式 multipart/form-data；

• 网络远程图：/wxwork/CdnUploadImgLink，JSON 传 url；
  返回 cdnkey、aeskey、md5、文件尺寸、缩略图参数。

4.2 CDN 文件 / 语音 (silk) 上传

• 本地文件：/wxwork/CdnUploadFile；

• 网络文件：/wxwork/UploadCdnLink；
  输出 cdnkey、aeskey、md5、文件名。

4.3 视频上传区分规则

1. ≤25MB：CDN 视频接口CdnUploadVideo/UploadCdnVideoLink；

4.4 文件下载渠道区分（重要）

1. 企业内部好友 / 内部群文件：使用 CDN 下载接口；

1. 外部微信联系人（个微）发送的图片、文件：专用外部下载接口，不可复用 CDN，否则 403 无权限。

5 群发目标拉取接口

用于获取vids数组（群发接收人 ID）

5.1 外部联系人列表

接口：/wxwork/GetExternalContacts，分页查询所有外部客户 vid，可过滤拉黑、已删除联系人。

5.2 群聊相关接口

1. /wxwork/GetChatroomMembers：分页获取全部客户群 roomid；

1. /wxwork/GetSessionRoomList：获取会话列表内群；

1. /wxwork/GetRoomUserList：根据 roomid 查询群内成员 vid，用于定向群内群发；

6 群发核心接口 SendGroupsMsg

接口地址

https://wechatapi.apifox.cn//wxwork/SendGroupsMsg

核心特性修正

1. 无每日发送限制：不存在单个客户 / 群每日仅 1 条群发规则，可按需批量推送；

1. 底层逻辑：复用所有单发消息能力，仅支持批量收件人；

1. 入参约束：vids 数组只能全为联系人 vid 或 全为群 roomid，禁止混合。

请求参数

| 参数 | 类型 | 必填 | 说明 |
| ---- | ---- | ---- |
| uuid | string | 是 | 实例唯一标识，缺失返回 500 错误 |
| vids | array | 是 | 接收人 ID 数组，联系人 = vid，群 = roomid |
| isroom | boolean | 是 | true = 群发群；false = 群发外部 / 内部联系人 |
| msg_list | array | 是 | 消息内容数组，支持多类型混合 |

msg_list 各消息类型模板

1 纯文本 type=0

2 CDN 图片 type=14

3 CDN 文件 type=15

4 链接卡片 type=13

5 小程序 type=78

6 超大视频 type=22（大于 25MB）

完整群发请求示例（外部联系人图文混合群发）

接口返回示例

msg_id 为本次群发批次标识，用于回调匹配发送回执。

7 配套消息能力接口

群发底层复用单发逻辑，如需单独给单个用户发消息，使用对应单发接口：

1. 文本消息/wxwork/SendTextMsg

1. 图文表情/wxwork/SendTextAndExpMsg

1. CDN 图片 / 文件 / 语音 / 视频单发接口

1. 撤回消息/wxwork/RevokeMsg：入参 msgid、roomid（单聊填 0）

1. 标记已读/wxwork/MarkAsRead：消除会话小红点

1. 引用回复/wxwork/sendQuoteMsg：回复客户历史消息

1. 语音转文字/wxwork/SpeechToTextEntity：解析语音内容

8 消息回调业务作用

1. 接收群发每条消息的发送回执（匹配 msg_id 判断是否发送成功）；

1. 接收外部客户、群内成员实时回复消息；

1. 接收群变更、好友新增等事件推送；

1. 离线同步接口仅拉取历史消息，实时消息全部依赖回调。

9 标准完整业务流程

1. 调用/wxwork/init初始化实例，获取 uuid；

1. 调用/wxwork/SetCallbackUrl配置消息回调地址；

1. 执行登录流程（扫码 / 自动登录）；

1. 调用/wxwork/SyncAllData同步离线历史消息；

1. 拉取群发目标：外部联系人 / 群列表，整理 vids 数组；

1. 上传图片 / 文件 / 视频等素材，保存 cdnkey/aeskey/md5；

1. 组装 msg_list，调用SendGroupsMsg执行群发；

1. 监听回调服务，接收每条消息发送回执与客户回复；

1. 可选：撤回错误消息、标记会话已读。

10 异常与错误处理方案

10.1 高频报错：uuid 参数不存在

返回：{"errcode":500,"errmsg":"uuid参数不存在"}
处理方案：校验请求 JSON 顶层是否携带 uuid 字段，字段名无拼写错误。

10.2 登录相关异常

• 二维码过期：重新调用getQrCode刷新；

• 验证码报错qrcode_not need verify：不要提前关闭手机验证码弹窗，重新获取二维码。

10.3 群发业务异常

1. vids 同时存在联系人 + 群：拆分两次群发，isroom 分别传 false/true；

1. 多媒体消息发送失败：校验上传全套 cdnkey/aeskey/md5/fileSize 参数是否齐全；

1. 文件下载 403：区分内外联系人渠道，外部客户使用专属下载接口。

10.4 通用接口异常

errcode≠0 时，执行阶梯重试（1s/3s/10s），超过 3 次记录失败日志人工排查。

11 开发约束与风控说明

1. 实例隔离：每个 uuid 对应独立企微 iPad 账号，多账号群发必须分开初始化，不可共用；

1. 代理区分：proxySituation=1 全局代理永久不可取消，自动化群发推荐使用 0 临时代理；

1. 文件渠道隔离：外部微信联系人素材禁止调用 CDN 下载接口，权限拦截；

1. 风控规则：无每日群发次数限制，但短时间大批量高频群发会触发企微风控，导致账号登录受限，建议分批延时推送；

1. 素材管理：群发素材按需上传，无需长期持久存储 cdn 等参数，节省存储资源。