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

文档基础信息

项目

详情

API接口调用文档

https://wechatapi.apifox.cn/

官方地址

https://www.jikehudong.com/

请求规范

绝大多数接口 POST + application/json；文件上传 POST + multipart/form-data

核心标识

uuid（企微实例唯一标识，全接口必传，缺失返回 500 错误：uuid 参数不存在）

修正核心点

原文档描述的「单个外部联系人每日仅接收 1 条群发」为错误说明，SendGroupsMsg 群发接口无每日发送限制；群发底层逻辑与单发消息一致，复用各类消息发送能力，无独立限流规则

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

1.1 分层架构

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

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

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

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

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

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

1.2 核心字段释义

字段

说明

uuid

单个 iPad 企微实例唯一标识，所有接口必填，不传直接返回 {"errcode":500,"errmsg":"uuid参数不存在"}

vid

用户 ID，外部联系人以 7881 开头，企业内部成员 16888 开头

roomid

群聊唯一 ID，群群发时作为 vids 数组参数

cdnkey/aeskey/md5

多媒体消息三要素，上传接口返回，图片 / 文件 / 视频消息必填

msg_id

单条消息唯一编号，用于撤回、回执匹配

server_id

消息序列号，离线同步接口分页游标

msg_list

群发接口专属参数，支持多类型消息混合组装

1.3 群发核心逻辑说明

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

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

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

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

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": "",  "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

两种推送模式

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

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 标准回调示例：

@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 登录全系列接口

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

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

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

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

3.4 实例管理辅助接口

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

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

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

/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 视频上传区分规则

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

25MB 大视频：走大文件上传链路：① /wxwork/GetBigAuthkey 获取上传凭证 authkey、filekey；② 本地文件：BigUploadFile；网络文件：BigFileUploadLink；③ 返回 file_id 作为群发 cdnkey。

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

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

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

5 群发目标拉取接口

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

5.1 外部联系人列表

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

5.2 群聊相关接口

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

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

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

6 群发核心接口 SendGroupsMsg

接口地址

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

核心特性修正

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

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

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

请求参数

msg_list 各消息类型模板

1 纯文本 type=0

{"type": 0,"content":"本次活动通知内容"}
2 CDN 图片 type=14
json{  "type": 14,  "cdnkey": "上传返回cdnkey",  "aeskey": "加密密钥",  "md5": "文件md5",  "fileSize": 3243381}
3 CDN 文件 type=15
json{  "type": 15,  "cdnkey": "xxx",  "aeskey": "xxx",  "md5": "xxx",  "fileSize": 2813,  "fileName": "活动资料.pdf"}
4 链接卡片 type=13
json{  "type": 13,  "url": "https://xxx.com",  "title": "活动详情",  "content": "活动详细介绍",  "headImg": "封面图片地址"}
5 小程序 type=78
json{  "type": 78,  "title": "小程序标题",  "desc": "简介",  "weappIconUrl": "小程序头像",  "pagepath": "pages/index/index",  "appid": "wxxxxxxx",  "username": "gh_xxx@app",  "cdnkey": "封面上传参数",  "md5": "xxx",  "aeskey": "xxx",  "fileSize": 15444}
6 超大视频 type=22（大于 25MB）
json{  "type": 22,  "cdnkey": "大文件上传返回file_id",  "file_name": "活动视频.mp4",  "md5": "文件md5",  "video_duration": 178,  "fileSize": 63647298,  "imgurl": "视频封面图url"}

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

{  "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e71a1e",  "vids": [7881302555913738,7881302555913999],  "isroom": false,  "msg_list": [    {      "type": 0,      "content": "各位客户，本次活动通知，请查看附件图片与详情链接"    },    {      "type": 14,      "cdnkey": "306b020102046430620201000204060b19e102034c4cd20204986b259902046807456b042466303163353336302d636437642d346335302d626238632d38356638333361613238376402031038000203317d8004107d8a8e79499210c6242c36afd10647c70201010201000400",      "aeskey": "B26DB4824341608DB848A2DA563B7147",      "md5": "7d8a8e79499210c6242c36afd10647c7",      "fileSize": 3243381    },    {      "type": 13,      "url": "https://www.baidu.com",      "title": "活动详情链接",      "content": "活动完整规则说明",      "headImg": "https://xxx/cover.png"    }  ]}
接口返回示例
json{  "data": {    "msg_id": 1066230  },  "errcode": 0,  "errmsg": "ok"}
msg_id 为本次群发批次标识，用于回调匹配发送回执。

7 配套消息能力接口

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

文本消息 /wxwork/SendTextMsg

图文表情 /wxwork/SendTextAndExpMsg

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

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

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

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

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

8 消息回调业务作用

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

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

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

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

9 标准完整业务流程

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

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

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

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

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

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

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

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

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

10 异常与错误处理方案

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

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

10.2 登录相关异常

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

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

10.3 群发业务异常

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

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

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

10.4 通用接口异常

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

11 开发约束与风控说明

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

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

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

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

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