QiWX企业微信API回调云上SAAS服务平台外部群接入AI机器人消息推送系统发送信息-171主机测评

QiWX 企业微信API回调云上SAAS服务平台

1. 项目概览

QiWX 开放平台是一个企业微信自动化连接器，通过统一的 HTTP API，使企业自有系统（CRM、ERP、OA、AI 大模型、运营后台、告警系统等）具备操控企业微信账号的能力。

平台能力覆盖：

设备创建、恢复、扫码登录、免扫码登录、登录状态查询、停用设备。
企业微信消息发送：文本、混合文本、图片、文件、语音、视频、链接、名片、小程序、视频号、GIF 表情等。
消息同步、历史消息分页、撤回消息、修改消息状态、语音转文字、群发助手、群消息置顶。
文件与媒体上传下载：本地文件上传、URL 上传、企微/个微文件下载、异步上传下载、大文件处理、CDN 转 URL。
联系人管理：内外部联系人分页、详情批量查询、搜索、添加好友、同意申请、删除联系人、更新备注/描述/手机号、OpenID 转换。
群管理：创建群、邀请/移除成员、群详情、群分页、群二维码、群公告、群名、群备注、群内昵称、管理员、群主转让、退群、解散、群开关项管理等。
会话管理：会话分页、会话组查询、会话置顶/免打扰/保存/标记等编辑能力。
朋友圈管理：上传素材、发朋友圈、分页查询、详情批量查询、点赞/取消点赞、评论/追评、删除评论、删除朋友圈。
标签管理：企业/个人标签分页，个人标签增删改，客户标签增删。
个人账号能力：个人资料查询/更新、账号退出、二维码名片、企业信息查询、收藏消息/收藏 GIF 表情。
回调能力：账号状态变化、API 异步任务结果、系统消息、普通消息接收。

平台核心定位：只提供消息路由与执行能力，不存储用户任何数据。业务侧应自行保存联系人、群、消息、回调事件等数据，并基于回调做增量维护。

2. 目录结构与资料来源

当前知识库目录按业务模块组织：

knowledge/
├── 开发前必读.md
├── 回调结构说明.md
├── 客户用例.md
├── 个人模块/
├── 会话模块/
├── 回调模块/
├── 朋友圈模块/
├── 标签模块/
├── 消息模块/
│ └── 文件与媒体（下载-上传）/
├── 登录模块/
├── 群模块/
└── 联系人模块/

重要原始文档：

文件内容

开发前必读.md	平台定位、快速发送消息示例、核心场景、合规提醒。
回调结构说明.md	回调类型、账号状态回调、API 异步消息、系统消息、普通消息和 msgType 说明。
客户用例.md	Flask HTTP 回调接收服务示例，包含无鉴权和 Authorization 鉴权两种方式。
消息模块/引用消息发送说明.md	文本消息与混合文本消息携带引用消息的格式和限制。

3. 通用调用规范

3.1 API 域名与统一入口

绝大多数 JSON API 通过统一入口调用：

POST http://api.qiwx.online/work-weixin/api/doApi

文件上传类接口使用 multipart/form-data 入口：

POST http://api.qiwx.online/work-weixin/api/doFileApi

3.2 鉴权方式

所有请求都需要在 Header 中携带平台 Token：

X-QIWEI-TOKEN: YOUR_API_KEY
Content-Type: application/json

文件上传时：

X-QIWEI-TOKEN: YOUR_API_KEY
Content-Type: multipart/form-data; boundary=…

注意：示例脚本中出现的 Token、guid、userId、roomId 等均应替换为真实业务环境参数。生产文档和代码中建议统一使用环境变量或配置中心，不要硬编码密钥。

3.3 JSON API 请求结构

统一请求体格式：

{
"method": "/msg/sendText",
"params": {
"guid": "你的设备ID",
"toId": "接收人userId或群roomId",
"content": "你好，这是你的第一条企业微信消息"
}
}

字段说明：

字段类型说明

method	string	具体业务接口路径，例如 /msg/sendText。
params	object	具体接口参数，不同 method 对应不同结构。
guid	string	设备 ID，绝大多数接口必填，用于标识哪个企业微信设备执行操作。

3.4 通用响应结构

常见成功响应：

{
"code": 0,
"msg": "success"
}

或：

{
"code": 200,
"data": {},
"msg": "成功"
}

实际响应字段以具体接口为准。建议业务侧统一封装客户端：

检查 HTTP 状态码。

检查业务 code 或 errorCode。

记录 requestId，尤其是异步接口。

对异步任务等待回调，并通过 requestId 关联请求与结果。

3.5 常见关键 ID

ID/字段含义常见来源

guid	设备 ID	创建设备、控制台在线登录、恢复设备。
userId	联系人/账号用户 ID	联系人分页、联系人详情、消息回调。
toId	消息接收目标 ID	可以是用户 userId，也可以是群 roomId。
roomId	群 ID	群分页、会话分页、群详情、消息回调。
chatId / sessionId	会话 ID	会话分页、消息状态修改、撤回消息。
msgServerId	消息服务端 ID	消息回调、历史消息同步、发送结果。
msgUniqueIdentifier	消息唯一标识	消息回调、引用消息、去重。
msgSeq	消息分页游标	同步历史消息、收藏分页。
currentSeq	分页游标	会话分页、标签分页、外部联系人分页。
requestId	请求 ID	异步接口回调关联。
corpId	企业 ID	企业信息、添加企微、同意申请、标签 owner。
corpAgentId	企业应用 ID	OpenID 转换接口。

4. 快速接入流程

4.1 最小发送文本消息示例

curl -X POST http://api.qiwx.online/work-weixin/api/doApi \\
-H "X-QIWEI-TOKEN: YOUR_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
"method": "/msg/sendText",
"params": {
"guid": "你的设备ID",
"toId": "target_user_or_room_id",
"content": "你好，这是你的第一条企业微信消息",
"isNoNeedRead": true
}
}'

4.2 Python 通用调用封装建议

import http.client
import json

API_HOST = "api.qiwx.online"
API_PATH = "/work-weixin/api/doApi"
TOKEN = "YOUR_API_KEY"

def call_qiwx(method: str, params: dict):
conn = http.client.HTTPConnection(API_HOST)
payload = json.dumps({"method": method, "params": params}, ensure_ascii=False).encode("utf-8")
headers = {
"X-QIWEI-TOKEN": TOKEN,
"Content-Type": "application/json; charset=utf-8",
}
conn.request("POST", API_PATH, payload, headers)
res = conn.getresponse()
raw = res.read().decode("utf-8")
return res.status, raw

status, body = call_qiwx("/msg/sendText", {
"guid": "YOUR_GUID",
"toId": "TARGET_ID",
"content": "测试消息",
"isNoNeedRead": True,
})
print(status, body)

5. 登录模块：设备生命周期与登录流程

登录模块是后续所有接口调用的前置能力。业务系统必须先获得在线设备 guid，才能调用消息、联系人、群、朋友圈等接口。

5.1 标准扫码登录流程

1. 创建设备 /client/createClient
2. 获取二维码 /login/getLoginQrcode
3. 轮询二维码状态 /login/checkLoginQrCode
4. 如出现 6 位验证码状态，调用 /login/verifyLoginQrcode
5. 再次轮询 /login/checkLoginQrCode，直到 status = 2
6. 调用 /login/checkLogin 确认在线

5.2 登录状态码

二维码状态检测和用户状态查询中常见状态：

status / userOnlineStatus说明建议处理

-1	登录状态失效，需要重新扫码登录	重新获取二维码或恢复设备后再登录。
0	未登录，可免扫码登录	可尝试 /login/manualLogin。
1	已扫码，待手机端确认	继续轮询，建议 2-3 秒一次。
2	登录成功/在线	可开始调用业务接口。
3	登录失败	重新获取二维码或排查账号状态。
4	用户取消登录	结束流程或重新获取二维码。
10	已扫码确认，待输入 6 位验证码	调用 /login/verifyLoginQrcode，然后继续检测。

5.3 登录相关接口清单

示例文件method功能关键参数备注

登录模块/创建设备（步骤1）.py	/client/createClient	初始化云端设备实例	areaCode, proxyUrl, aid, deviceName, deviceType, clientVersion	创建/恢复设备后 5 分钟内未登录，实例会自动清理。
登录模块/二维码-获取（步骤2）.py	/login/getLoginQrcode	获取登录二维码	guid, useCache	首次登录 useCache=false；恢复设备后可 useCache=true。
登录模块/二维码状态-检测（步骤3）.py	/login/checkLoginQrCode	轮询扫码进度	guid	建议每 2-3 秒轮询一次。
登录模块/二维码-code验证（步骤4）.py	/login/verifyLoginQrcode	提交 6 位验证码	guid, code	验证后必须再次调用二维码状态检测。
登录模块/用户状态.py	/login/checkLogin	查询当前设备登录状态	guid	可用于启动前健康检查。
登录模块/用户登录（免扫码登录） .py	/login/manualLogin	免扫码登录	guid	仅适用于该设备曾扫码登录且手机端未剔除设备。
登录模块/恢复设备.py	/client/restoreClient	恢复离线设备	guid	离线后先恢复，再获取二维码扫码。
登录模块/停用设备.py	/client/stopClient	停用设备、释放资源	guid	更换新设备时遵循“先停再建”。

5.4 创建设备参数说明

参数说明

areaCode	地区代理，可为空。示例列出北京、上海、广东、四川等省市行政区划代码。
proxyUrl	自定义代理，目前只支持 socks5；格式如 socks5://user:password@ip:port。
aid	本地代理 Aid，需要配合本地 Aid 客户端持续运行，提供稳定网络环境。
deviceName	设备名称，例如“客服一号 Windows”。
deviceType	设备类型，0 表示 iPad，2 表示 Windows。
clientVersion	客户端版本号，无特殊需求可为空。示例说明 iPad 最新版 5.0.2.206376、Windows 最新版 5.0.2.6011。

6. 回调模块：事件接收与异步结果

QiWX 支持 HTTP 回调。消息会通过消息订阅接口配置的 HTTP 回调地址发送。

6.1 配置回调

示例文件method功能参数

回调模块/setcallback.py

/client/setCallback

设置回调地址

callbackUrl, authType, authSecret

参数说明：

参数说明

callbackUrl	业务系统接收回调的 HTTP URL。
authType	鉴权方式。示例使用 Authorization，留空表示不鉴权。
authSecret	鉴权密钥。留空表示不鉴权。

回调作用范围：按 Token 配置，一个 Token 下的所有账号共用此回调地址。回调内容中会包含 guid，业务系统应使用 guid 区分不同账号/设备。

6.2 Flask 回调接收示例

无鉴权版本：

from flask import Flask, request, jsonify
import json

app = Flask(__name__)

@app.route('/api/data', methods=['POST'])
def handle_data():
data = request.get_json()
if data is None:
return jsonify({"status": "error", "message": "Invalid JSON data"}), 400
print(json.dumps(data, indent=4, ensure_ascii=False))
return jsonify({"status": "success", "receivedData": data}), 200

if __name__ == '__main__':
app.run(debug=True, host='0.0.0.0', port=8888)

带 Authorization 鉴权版本核心逻辑：

import hmac

SECRET = "test123456"
sig = request.headers.get('Authorization', '')
if not hmac.compare_digest(sig, SECRET):
return jsonify({"status": "error", "message": "unauthorized"}), 401

6.3 回调外层结构

常见结构：

{
"code": 0,
"data": [
{
"guid": "设备ID",
"userId": "当前账号userId",
"requestId": "请求ID",
"customParam": "自定义参数",
"cmd": 15000,
"msgServerId": 1002114,
"msgType": 0,
"msgUniqueIdentifier": "消息唯一标识",
"senderId": 1688852365307991,
"receiverId": 0,
"fromRoomId": 10791082136095292,
"timestamp": 1709103900,
"msgData": {}
}
],
"msg": "成功"
}

6.4 回调类型 cmd

cmd类型说明

11016	账号状态变化消息	登录成功、注销、顶号、环境异常、登录态过期等。
20000	API 异步消息	异步上传/下载等任务结果，通过 requestId 与请求关联。
15500	VX 系统消息	联系人、标签、群、会话、朋友圈等系统事件。
15000	VX 普通消息	文本、图片、视频、文件、语音、链接、名片、撤回、已读等普通消息。

6.5 账号状态变化 cmd=11016

msgData.code 常见值：

code说明

10000	网络异常离线
11001	登录成功
11002	注销成功
11013	刷新 session 失败
11017	其它端顶号
11022	手机端主动退出，取消设备授权
11023	账号环境出现异常，请重新登录使用
11024	登录态已过期，请重新登录
11025	正在新设备上使用企业微信，需通过手机企业微信扫码安全验证

msgData.status 与登录状态码一致，serverReboot 用于标记服务重启维护/热修复。

6.6 API 异步消息 cmd=20000

异步文件上传/下载结果通过该回调返回。示例结构：

{
"cmd": 20000,
"requestId": "57a360fd-f920-4b4d-84c0-351ec1c63fe8",
"msgData": {
"cloudUrl": "2026-06-093xctawaihya.jpg"
}
}

处理建议：

发起异步任务时保存请求返回的 requestId。

收到回调时按 requestId 更新任务状态。

将 cloudUrl、上传后的 fileId、fileAesKey、fileMd5 等结果保存到业务库。

6.7 系统消息 cmd=15500 / 部分系统事件 cmd=15000

系统消息按 msgType / newMsgType 区分事件。

模块msgTypenewMsgType说明

联系人	2131	CONTACT_EXTERNAL_CHANGE	外部联系人备注/描述/手机号变动或删除。
联系人	2313	CONTACT_EXTERNAL_BLACKLIST	外部联系人加入黑名单。
联系人	2188	CONTACT_INTERNAL_CHANGE	内部联系人备注/描述变动。
联系人	2357	CONTACT_FRIEND_REQUEST_2357	好友申请通知，msgData 包含申请人信息。
联系人	2132	CONTACT_FRIEND_REQUEST_2132	好友申请通知。
联系人	2104	CONTACT_DND_TOP	联系人免打扰/置顶通知。
联系人	2115	CONTACT_MARK	联系人标记操作通知。
标签	2160	TAG_CHAT_CHANGE	聊天标签变动。
标签	2161	TAG_CHAT_CONTACT_CHANGE	聊天标签中的联系人变动。
标签	2185	TAG_CORP_ADD_DEL	企业标签新增或删除。
标签	2186	TAG_PERSONAL_ADD_DEL	个人标签新增或删除。
群	1001	GROUP_NAME_CHANGE	群名变更。
群	1002	GROUP_MEMBER_ADD	新增群成员。
群	1003	GROUP_MEMBER_REMOVE	移除群成员。
群	1005	GROUP_MEMBER_QUIT	群成员自己退群。
群	1006	GROUP_CREATE	群新增。
群	1011	GROUP_OPERATION_TIP	群操作提示。
群	1022	GROUP_OWNER_TRANSFER	转让群主。
群	1023	GROUP_DISMISS	群解散。
群	1029	GROUP_INVITE_APPLY	群成员邀请其他人进群申请。
群	1043	GROUP_ADMIN_CHANGE	群管理员变动。
群	2118	GROUP_INFO_CHANGE	群信息变动。
会话	2055	SESSION_CLEAR	清空聊天记录。
会话	2002	SESSION_DELETE	删除聊天。
会话	40	CALL_END	语音/视频通话结束通知。
会话	503/2166	CALL_NOTIFY	语音/视频通话通知。
朋友圈	2215	MOMENT_CHANGE	朋友圈变动通知。
朋友圈	517	MOMENT_PUSH	朋友圈推送通知。

6.8 普通消息 cmd=15000 的 msgType

msgTypenewMsgType说明

0 or 2	TEXT / TEXT_ALT	文本消息。
7 / 14 / 101	IMAGE / IMAGE_14 / IMAGE_101	图片消息。
22 / 23 / 103	VIDEO / VIDEO_23 / VIDEO_103	视频消息。
20 / 15 / 102	FILE_20 / FILE / FILE_102	文件消息；20 也用于大文件。
29 / 104	GIF_29 / GIF_104	GIF 表情。
6	LOCATION	位置消息。
13	LINK	链接卡片。
41	BUSINESS_CARD	名片。
26	RED_PACKET	红包。
16	VOICE	语音。
78	MINI_PROGRAM	小程序。
123	MIXED	图文混合消息。
141	VIDEO_CHANNEL	视频号。
146	LIVE	直播。
213	SOLITAIRE	接龙。
2001	READ_NOTIFY	消息已读通知。
2005	UNREAD_NOTIFY	消息未读通知。
2063	REVOKE	撤回消息。

普通消息的 msgData 会随 msgType 变化。例如：

文本：content, atList。
图片：fileAeskey, fileId, fileMd5, fileName, fileSize, imageHasHd。
个微图片：还可能包含 fileAuthkey, fileBigHttpUrl, fileMiddleHttpUrl, fileThumbHttpUrl。
视频：fileId, fileAeskey, fileMd5, fileSize, duration, coverImageId 等。
文件：fileId, fileAeskey, fileMd5, fileName, fileNameExt, fileSize。
语音：fileId, fileAesKey, fileMd5, fileSize, voiceTime，下载默认走企微文件下载，格式为 .silk。
位置：address, latitude, longitude, title, zoom。
链接：title, desc, iconUrl, linkUrl。
小程序：appid, username, pagepath, title, desc, coverImageId 等。
混合消息：数组，每项包含 subMsgType 与 subMsgData。

7. 消息模块

消息模块是使用最频繁的模块，支持单聊、群聊、多媒体消息、消息状态、历史同步、群发和群消息置顶。

7.1 普通发送接口清单

示例文件method功能关键参数

消息模块/发送纯文本消息.py	/msg/sendText	发送纯文本	guid, content, toId, isNoNeedRead
消息模块/发送混合文本消息.py	/msg/sendHyperText	发送混合文本、@人、系统表情	guid, content[], toId
消息模块/发送图片消息.py	/msg/sendImage	发送图片	fileAesKey, fileId, fileMd5, fileSize, filename, toId
消息模块/发送文件消息.py	/msg/sendFile	发送文件	fileAesKey, fileId, fileSize, filename, toId
消息模块/发送语音消息.py	/msg/sendVoice	发送语音（AMR）	fileAesKey, fileId, fileSize, voiceTime, toId
消息模块/发送视频消息.py	/msg/sendVideo	发送视频	fileAesKey, fileId, fileMd5, fileSize, filename, duration, previewImgUrl, toId
消息模块/发送链接消息.py	/msg/sendLink	发送链接卡片	title, iconUrl, linkUrl, desc, toId
消息模块/发送定位消息.py	/msg/sendLocation	发送地理位置	title, address, latitude, longitude, toId
消息模块/发送名片消息.py	/msg/sendPersonalCard	发送个人名片	sharedId, toId
消息模块/发送小程序消息.py	/msg/sendWeapp	发送小程序卡片	appId, coverFileAesKey, coverFileId, coverFileSize, pagePath, title, username, toId
消息模块/发送视频号消息.py	/msg/sendFeedVideo	发送视频号	channelName, channelUrl, coverUrl, encodeData, headImgUrl, feedId, feedNo, username, toId
消息模块/发送GIF表情消息.py	/msg/sendGif	发送 GIF 表情	wxFileUrl, toId

7.2 文本消息 /msg/sendText

参数：

参数说明

guid	设备 ID。
content	文本内容。
toId	接收方用户 ID 或群 ID。
isNoNeedRead	是否禁止回执，默认不禁止；布尔值。
reply	可选，引用消息对象；仅文本/混合文本支持引用。

7.3 混合文本 /msg/sendHyperText

content 是数组，每段有 subtype 和 text：

subtype含义text 说明

0	普通文本	直接写文本。
1	@ 用户	text 为对方 userId；如果为 "" 或特定约定可表示 @所有人（示例中 text 为空表示 @所有人）。
2	系统表情	如 [微笑][憨笑]。

示例：

{
"method": "/msg/sendHyperText",
"params": {
"guid": "YOUR_GUID",
"toId": "ROOM_OR_USER_ID",
"content": [
{"subtype": 2, "text": "[微笑][憨笑]"},
{"subtype": 1, "text": ""},
{"subtype": 0, "text": " 我是智能客服"}
]
}
}

7.4 引用消息发送

引用消息只支持：

/msg/sendText
/msg/sendHyperText

不支持图片、文件、语音、视频等其他发送接口直接携带引用。

可引用的消息类型：

type说明

0	文本
14	图片
15	文件
16	语音
23	视频
29	收藏/第三方微信表情

引用对象结构：

{
"reply": {
"type": 15,
"msgServerId": 1003054,
"userId": "原消息发送人ID",
"showName": "可选展示名",
"timeStamp": 1625957403,
"msgUniqueIdentifier": "原消息唯一标识",
"msgData": {
"fileId": "…",
"fileSize": 101317,
"fileMd5": "…",
"filename": "JPEG 图像.jpeg",
"filenameExt": "jpeg",
"fileAesKey": "…"
}
}
}

reply.msgData 随 reply.type 不同而不同，格式应参考接收消息回调中的 msgData。

7.5 多媒体消息发送前置流程

发送图片、文件、语音、视频、小程序封面等通常需要先上传文件或从回调中取得文件参数。

常见流程：

本地文件/URL → 上传接口 → 获得 fileId/fileAesKey/fileMd5/fileSize/filename → 调用 sendImage/sendFile/sendVideo/sendVoice

大文件/大视频：

大文件时 fileAesKey 可能为空。
fileId 需要使用上传返回的 fileConvertId。
大视频发送时也需要传 fileConvertId。
fileId 包含 * 字符时，部分字段可为空或需要额外上传 previewImgUrl。

7.6 历史消息与状态接口

示例文件method功能关键参数说明

消息模块/同步历史消息分页.py	/msg/syncMsg	同步历史消息分页	guid, msgSeq, limit	首次 msgSeq=0，后续传返回值。
消息模块/撤回消息.py	/msg/revokeMsg	撤回消息	guid, chatId, msgServerId	chatId 可选，等于 sessionId。
消息模块/修改消息状态.py	/msg/statusModify	修改会话/消息状态	guid, chatId, modifyType	1 已读，2 未读，3 清空聊天记录，4 从聊天列表删除。
消息模块/语音转文字-任务申请.py	/msg/voiceToTextApply	申请语音转文字	guid, msgServerId	返回 voiceId 后查询。
消息模块/语音转文字-任务查询.py	/msg/voiceToTextQuery	查询语音转文字结果	guid, msgServerId, voiceId	voiceId 来自申请接口。

7.7 群发助手

示例文件method功能参数

消息模块/群发助手发送.py	/msg/sendGroupMsg	创建/发送群发消息	guid, msgList, sendType, toIdList
消息模块/群发助手-规则查询.py	/msg/sendGroupMsgRule	查询群发规则	guid
消息模块/群发助手-状态查询.py	/msg/sendGroupMsgStatus	查询群发状态	guid, groupMsgId, endDetailId

群发限制：

每天只能对每个客户或群执行一次群发。

群主可直接创建并发送群发消息。

msgList 中消息字段与普通发送消息一致，但不需要 toId。

支持消息类型：0 文本、13 链接、14 图片、15 文件、23 视频、78 小程序。

sendType=0 表示外部联系人，sendType=1 表示外部群。

7.8 群消息置顶

示例文件method功能关键参数

消息模块/群消息置顶-列表.py	/msg/roomTopMessageList	查询群置顶消息列表	guid, roomId
消息模块/群消息置顶-添加.py	/msg/roomTopMessageSet	添加置顶消息	guid, roomId, msgId, msgSenderId, msgTimestamp, msgData, msgType
消息模块/群消息置顶-移除.py	/msg/roomTopMessageSet	移除置顶消息	guid, roomId, seq

限制：群消息置顶功能仅限群主。

8. 文件与媒体模块

文件与媒体能力既服务于消息发送，也服务于朋友圈、收藏、GIF 表情等功能。

8.1 上传接口

示例文件method入口功能参数

消息模块/文件与媒体（下载-上传）/本地文件上传.py	/cloud/cdnBigUpload	doFileApi	本地文件 multipart 上传	method, guid, file, fileType
消息模块/文件与媒体（下载-上传）/文件上传-URL.py	/cloud/cdnBigUploadByUrl	doApi	通过在线 URL 上传	guid, filename, fileUrl, fileType
消息模块/文件与媒体（下载-上传）/企微文件异步上传.py	/cloud/cdnUploadByUrlAsync	doApi	企微普通文件异步 URL 上传	guid, filename, fileUrl, fileType
消息模块/文件与媒体（下载-上传）/企微大文件异步上传.py	/cloud/cdnBigFileUploadByUrlAsync	doApi	企微大文件/大视频异步上传	guid, filename, fileUrl, fileType

fileType 常见含义：

fileType说明

1	jpg 图片
4	mp4 视频
5	文件，也包括语音 silk/amr 文件
22	大视频
35	大文件

上传注意：

本地上传使用 multipart/form-data，需要手动构造 method、guid、file、fileType 字段。
示例提示：上传文件超过 5M，建议使用异步上传。
异步上传结果通过 cmd=20000 回调返回，需要用 requestId 关联。

8.2 下载接口

示例文件method功能参数说明

企微文件下载.py	/cloud/wxWorkDownload	下载企微文件/图片/视频/语音	guid, fileAeskey, fileId, fileSize, fileType	同步下载。
企微文件异步下载.py	/cloud/wxWorkDownloadAsync	异步下载企微文件	同上	通过回调返回结果。
企微大文件异步下载.py	/cloud/cdnBigFileDownloadByUrlAsync	下载大文件/大视频	guid, filekey, fileId, fileSize, filename, fileType	文件大于 20M 使用。
个微文件下载.py	/cloud/wxDownload	下载个微文件/图片/视频/语音	guid, fileAeskey, fileAuthkey, fileSize, fileType, fileUrl	同步下载。
个微文件异步下载.py	/cloud/wxDownloadAsync	异步下载个微文件	同上	通过回调返回结果。
文件CDN转URL.py	/cloud/cdnWxDownload	将企微 CDN 文件参数转官方 URL	guid, fileAeskey, fileId, fileMd5	返回官方 CDN 地址。

下载结果中的云资源地址是临时资源，非官方 CDN，通常 7-15 天不定期清理，请及时下载或转存。

8.3 下载 fileType 选择

fileType说明

1	大图。如果接收图片消息字段 imageHasHd=1 或个微有 fileBigHttpUrl，可用该类型。
2	小图。如果 imageHasHd=0 或个微有 fileMiddleHttpUrl，可用该类型。
3	视频/图片缩略图，对应 thumb 字段。
4	视频。
5	文件/语音文件。

9. 联系人模块

联系人模块覆盖外部联系人、内部联系人、好友申请、搜索、添加、删除、更新和 OpenID 转换。

9.1 联系人查询与同步

示例文件method功能关键参数说明

联系人模块/外部联系人分页.py	/contact/getWxContactList	分页拉取外部联系人/好友申请	guid, currentSeq, limit, bizType	首次 currentSeq=0，后续传上次返回值；bizType=1 外部联系人变动，bizType=2 好友申请数据。
联系人模块/内部联系人分页.py	/contact/getWxWorkContactList	分页拉取内部联系人	guid, clientVersion, limit	联系人较多时分页；首次 clientVersion 为空，后续传返回值获取变更。
联系人模块/联系人详情-批量.py	/contact/batchGetUserinfo	批量查询联系人详情	guid, userIdList	支持好友、非好友；建议先分页获取 userId 并本地缓存。
联系人模块/联系人搜索.py	/contact/searchContact	搜索联系人	guid, keyword	keyword 可为手机号等搜索词。
联系人模块/Openid.py	/contact/openid	转换 OpenID/external_userid	guid, userIdList, corpAgentId	OpenID 即官方 API 的 external_userid。

建议数据同步模式：

首次全量调用外部联系人分页/内部联系人分页。

使用联系人详情批量接口补全资料。

将数据缓存到本地数据库。

后续依赖回调事件和分页游标做增量更新。

9.2 联系人添加与申请处理

示例文件method功能参数

联系人模块/添加个微.py	/contact/addSearchWxContact	添加微信联系人	guid, userId, unionId, verifyText
联系人模块/添加企微.py	/contact/addSearchWxWorkContact	添加企业微信联系人	guid, userId, corpId, ticket, verifyText
联系人模块/添加企微名片.py	/contact/addCardContact	通过名片添加企微联系人	guid, presenterId, fromRoomId, userId, verifyText
联系人模块/添加群成员好友.py	/contact/addRoomContact	添加群成员为好友	guid, roomId, userId, verifyText
联系人模块/添加删除联系人.py	/contact/addDeletedContact	添加已删除联系人	guid, userId, verifyText
联系人模块/同意申请.py	/contact/agreeContact	同意好友申请	guid, userId, corpId

9.3 联系人更新与删除

示例文件method功能参数

联系人模块/外部联系人信息-更新.py	/contact/updateWxContact	更新外部联系人备注/描述/手机号	guid, userId, remark, desc, mobileList
联系人模块/内部联系人信息-更新.py	/contact/updateWxWorkContact	更新内部联系人备注/描述	guid, userId, remark, desc
联系人模块/删除联系人.py	/contact/deleteContact	删除联系人	guid, userId

10. 群模块

群模块用于群生命周期、群资料、成员、权限和 OpenID 转换。

10.1 群查询

示例文件method功能参数说明

群模块/群分页.py	/room/getRoomList	查询本人创建的群	guid, nextStartIndex	仅支持本人创建群；查全部群建议结合会话分页。
群模块/群详情-批量.py	/room/batchGetRoomDetail	批量查询群详情	guid, roomIdList	先用群分页获取 roomId，再批量详情。群成员名称需调用联系人详情。
群模块/群成员变动查询.py	/room/getRoomIncrSync	查询群成员增量变动	guid, roomId, ver, nowMemberCount	适合大群，降低全量同步成本；首次 ver=0。
群模块/群二维码.py	/room/getRoomQrCode	获取群二维码	guid, roomId
群模块/OpenID.py	/room/openid	群 OpenID 转换	guid, roomId, corpAgentId	需要企业应用 ID。

10.2 群生命周期与成员管理

示例文件method功能参数

群模块/创建群.py	/room/createRoom	创建群	guid, isOuterRoom, memberList
群模块/邀请-添加成员.py	/room/inviteRoomMember	邀请/添加群成员	guid, roomId, isOuterRoom, memberList
群模块/移除成员.py	/room/removeRoomMember	移除群成员	guid, roomId, isOuterRoom, memberList
群模块/接受群邀请-By链接.py	/room/agreeInviteByLink	通过邀请链接入群	guid, joinCode, joinType
群模块/退群.py	/room/quitRoom	当前账号退群	guid, roomId
群模块/群解散.py	/room/dismissRoom	解散群	guid, roomId
群模块/转让群主.py	/room/changeRoomMaster	转让群主	guid, roomId, newOwnerId

10.3 群资料修改

示例文件method功能参数

群模块/修改群名称.py	/room/modifyRoomName	修改群名称	guid, roomId, name
群模块/修改群备注.py	/room/modifyRoomRemarkName	修改群备注	guid, roomId, remarkName
群模块/修改群公告.py	/room/modifyRoomNotice	修改群公告	guid, roomId, notice
群模块/修改群内昵称.py	/room/modifyRoomNickname	修改当前账号群内昵称	guid, roomId, nickname

10.4 群管理权限与开关

示例文件method功能参数注意

群模块/添加群管理员.py	/room/roomAddAdmin	添加群管理员	guid, roomId, memberList	通常需要群主权限。
群模块/取消群管理员.py	/room/roomRemoveAdmin	取消群管理员	guid, roomId, memberList	通常需要群主权限。
群模块/开启群邀请确认.py	/room/openInviteConfirm	开启/关闭群邀请确认	guid, roomId, isOpen, roomFlag	roomFlag 传错可能导致群其它状态错乱。
群模块/开启群改名.py	/room/enableChangeRoomName	开启/关闭群成员改名	guid, roomId, newFlag, disable	newFlag 从群详情或群成员变动接口获取，注意区别 roomFlag 与 roomNewFlag。
群模块/禁止群成员互相添加.py	/room/prohibitAddMember	禁止/允许群成员互相添加	guid, roomId, newFlag, disable	同样依赖正确的 newFlag。

11. 会话模块

会话模块用于获取聊天会话、会话组，以及对会话进行置顶、免打扰、保存到通讯录、标记等操作。

示例文件method功能参数说明

会话模块/会话分页.py	/session/getSessionPage	分页获取会话	guid, currentSeq	原路径为 /session/getSessionList，不向下兼容；示例备注游标暂时不支持。
会话模块/会话组-查询.py	/session/getSessionList	查询会话组	guid
会话模块/会话组-编辑.py	/session/setSessionCmd	编辑会话状态	guid, chatId, chatType	chatId 为会话 ID。

chatType 含义：

chatType操作

1	置顶
2	取消置顶
3	开启免打扰
4	取消免打扰
5	保存群聊到通讯录
6	从通讯录移除群聊
7	标记
8	取消标记

12. 朋友圈模块

朋友圈模块支持素材上传、发布、查询、互动和删除。

12.1 接口清单

示例文件method功能参数

朋友圈模块/文件上传.py	/sns/upload	上传朋友圈素材	multipart：method, guid, file, fileType
朋友圈模块/发送朋友圈.py	/sns/postSns	发布朋友圈	guid, postType, content, visibleUserIdList, mediaList, linkInfo
朋友圈模块/朋友圈列表分页.py	/sns/getSnsRecord	分页查询朋友圈	guid, maxSeq
朋友圈模块/获取详情-批量.py	/sns/getSnsDetail	批量查询朋友圈详情	guid, snsIdList
朋友圈模块/点赞-取消赞.py	/sns/snsLike	点赞/取消点赞	guid, snsId, snsStatus
朋友圈模块/评论-追评.py	/sns/snsComment	评论/回复评论	guid, snsId, content, refCommentId
朋友圈模块/评论删除 .py	/sns/deleteSnsComment	删除评论	guid, snsId, content, commentId
朋友圈模块/删除朋友圈.py	/sns/deleteSns	删除朋友圈	guid, snsId

12.2 发布朋友圈 /sns/postSns

关键参数：

参数说明

guid	设备 ID。
postType	0 表示图片/视频；1 表示链接/视频号。
content	朋友圈文字内容。
visibleUserIdList	指定好友可见列表；可不传或传空，表示全部好友可见。
mediaList	图片/视频媒体列表。
linkInfo	链接或视频号信息；postType=1 时必填，postType=0 时可置空。

mediaList.fileType：

fileType说明

1	图片
2	视频
3	视频缩略图

发送视频时，mediaList 必须携带视频与视频缩略图参数，通常成对出现。

视频号/链接 linkInfo 常见字段：

title：标题；视频号消息回调中的 channelName 可作为来源。
contentUrl：链接地址。
wxFinderInfo.desc：视频号描述或自定义文本。
wxFinderInfo.coverUrl / thumbUrl：封面。
wxFinderInfo.extras：视频号回调中的 encodeData。
wxFinderInfo.feedId, feedNo。
wxFinderInfo.avatar, nickname。
wxFinderInfo.feedType：视频号示例中为 4。

12.3 朋友圈互动

点赞：snsStatus=0。
取消点赞：snsStatus=1。
评论：refCommentId=0 或不传，表示一级评论。
回复评论：refCommentId 传被回复评论 ID。
删除评论：使用 commentId。

13. 标签模块

标签分为企业标签和个人标签。客户标签增删接口要求标签 ID、标签分组 ID、标签 owner 一一对应。

示例文件method功能参数说明

标签模块/列表分页.py	/label/syncLabelList	标签分页同步	guid, currentSeq, labelType	labelType=1 企业标签，labelType=2 个人标签。
标签模块/个人标签-增删改.py	/label/editLabel	个人标签新建/删除/修改	guid, opType, paramList	opType=1 新建，2 删除，3 修改。
标签模块/客户标签-增删.py	/label/contactEditLabel	给客户增加/删除标签	guid, opType, paramList	opType=1 增加成员，2 删除成员。

13.1 个人标签编辑 /label/editLabel

opType：

opType操作必填字段

1	新建标签	labelName, labelSuperId
2	删除标签	labelId
3	修改标签	labelId, labelName, labelSuperId

13.2 客户标签增删 /label/contactEditLabel

paramList 中字段：

字段说明

labelIdList	标签 ID 列表。
labelSuperIdList	标签所属分组 ID 列表。
labelOwnerList	个人标签传标签创建人 userId；企业标签传 corpId。
userId	目标客户 userId。

要求：labelIdList、labelSuperIdList、labelOwnerList 必须一一对应，数组长度保持一致。

14. 个人模块

个人模块用于当前账号资料、企业信息、二维码名片、收藏和退出。

示例文件method功能参数说明

个人模块/获取个人信息.py	/user/getProfile	查询个人信息	guid	guid 是后台登录设备 ID。
个人模块/更新个人信息.py	/user/setProfile	更新个人资料	guid, name, alias, email, mobile, address, gender	gender=1 男，2 女。
个人模块/生成二维码.py	/user/getQrcodeCard	生成个人二维码名片	guid
个人模块/查询企业信息.py	/user/getCorpInfo	查询企业信息	guid, corpIdList	corpIdList 为空时查询当前账号企业。
个人模块/账号退出.py	/user/logout	账号退出	guid
个人模块/个人收藏-分页.py	/msg/syncCollectionMsg	收藏分页	guid, msgSeq, limit	返回表情收藏列表和消息收藏列表；首次 msgSeq=0，后续传返回 seq。
个人模块/个人收藏-添加GIF表情.py	/msg/insertCollectionMsg	添加 GIF 表情到收藏	guid, msgData, type	type=29 表示添加表情；msgData 包含 fileMd5, fileHttpUrl。

15. 典型业务场景设计

15.1 AI 自动客服

目标：企业微信收到客户消息后，由大模型生成回复并发送。

推荐流程：

1. 配置回调 /client/setCallback
2. 收到普通消息 cmd=15000，识别 msgType=0/2 文本
3. 根据 guid、senderId、fromRoomId 判断账号、客户、群聊上下文
4. 从本地数据库读取客户资料、历史消息、标签、群信息
5. 调用 AI 大模型生成回复
6. 调用 /msg/sendText 或 /msg/sendHyperText 回复
7. 将收发消息、requestId、msgUniqueIdentifier 落库，防止重复处理

注意：

群消息需区分 fromRoomId 与 senderId。
必须对回调做幂等处理，可用 msgUniqueIdentifier 去重。
如果要引用原消息，只能使用 /msg/sendText 或 /msg/sendHyperText 的 reply 字段。

15.2 CRM 联系人同步

目标：把企业微信联系人同步到 CRM，保持备注、标签、手机号等信息更新。

推荐流程：

首次同步：
1. /contact/getWxContactList 获取外部联系人
2. /contact/batchGetUserinfo 批量补充详情
3. /label/syncLabelList 同步企业/个人标签
4. 落库 userId、corpId、标签、备注、描述、手机号

增量同步：
1. 监听 CONTACT_EXTERNAL_CHANGE / CONTACT_FRIEND_REQUEST 等回调
2. 收到事件后再次调用外部联系人分页或详情接口
3. 根据 currentSeq 和本地更新时间做增量更新

15.3 私域群运营

目标：管理群、群发通知、维护群成员和群设置。

常用接口：

查询群：/room/getRoomList, /room/batchGetRoomDetail, /session/getSessionPage。
成员管理：/room/inviteRoomMember, /room/removeRoomMember, /room/getRoomIncrSync。
群资料：/room/modifyRoomName, /room/modifyRoomNotice, /room/modifyRoomRemarkName。
权限：/room/roomAddAdmin, /room/openInviteConfirm, /room/prohibitAddMember。
群发：/msg/sendGroupMsg, /msg/sendGroupMsgStatus。
群置顶：/msg/roomTopMessageSet。

15.4 朋友圈运营

目标：发布朋友圈并跟踪互动。

推荐流程：

1. 图片/视频素材上传 /sns/upload
2. 发布朋友圈 /sns/postSns
3. 定期或按回调查询 /sns/getSnsRecord
4. 需要详情时 /sns/getSnsDetail
5. 互动：/sns/snsLike、/sns/snsComment
6. 删除：/sns/deleteSnsComment、/sns/deleteSns

15.5 文件收发与归档

目标：接收企业微信/微信文件并保存到业务系统，也可从系统发送文件给客户。

接收归档：

1. 收到文件/图片/视频/语音消息回调
2. 根据 msgType 判断是企微还是个微、普通文件还是大文件
3. 调用对应下载接口
4. 下载结果及时转存到自有对象存储
5. 保存 fileMd5、fileSize、filename、消息 ID、发送人、接收人

发送文件：

1. 本地文件或 URL 上传到 QiWX CDN
2. 保存返回的 fileId/fileAesKey/fileMd5/fileSize/filename
3. 调用 /msg/sendFile、/msg/sendImage、/msg/sendVideo 或 /msg/sendVoice

16. 开发注意事项与最佳实践

16.1 安全与合规

请勿将本服务用于违法用途，如广告骚扰、诈骗等。
Token、guid、用户 ID 等敏感信息不要写入公开仓库。
回调接口建议开启鉴权，并使用 HTTPS。
对外发送消息、群发、添加好友、朋友圈发布等能力应加业务风控、频控和审计。

16.2 幂等与去重

回调可能因为网络重试、服务重启、业务处理超时等原因重复到达。建议：

普通消息使用 msgUniqueIdentifier 去重。
异步任务使用 requestId 去重。
账号状态变化可用 guid + code + timestamp 做状态流转判断。

16.3 本地缓存

官方示例多次提示：联系人、群详情等不应频繁重复拉取。

建议本地缓存：

联系人基础信息、备注、手机号、标签。
群详情、群成员、群权限 flag。
会话 ID 与 roomId/userId 映射。
上传后的文件参数。
消息回调原始数据。

16.4 分页游标

常见游标：

游标使用接口首次值后续值

msgSeq	/msg/syncMsg, /msg/syncCollectionMsg	0	返回值中的 msgSeq 或 seq。
currentSeq	/contact/getWxContactList, /label/syncLabelList, /session/getSessionPage	0	返回值中的 currentSeq。
nextStartIndex	/room/getRoomList	0	返回值中的 nextStartIndex。
clientVersion	/contact/getWxWorkContactList	空字符串	上一次返回的版本值。
maxSeq	/sns/getSnsRecord	0	查询指定毫秒时间戳之前发布的朋友圈。
ver	/room/getRoomIncrSync	0	返回的群成员变动偏移量。

16.5 异步接口处理

异步接口包括：

/cloud/cdnUploadByUrlAsync
/cloud/cdnBigFileUploadByUrlAsync
/cloud/wxWorkDownloadAsync
/cloud/wxDownloadAsync
/cloud/cdnBigFileDownloadByUrlAsync

处理模式：

1. 发起请求，保存 requestId
2. 任务状态设为 processing
3. 等待 cmd=20000 回调
4. 使用 requestId 匹配任务
5. 更新结果字段和任务状态
6. 超时未回调时触发补偿或人工排查

16.6 群 flag 操作风险

/room/openInviteConfirm、/room/enableChangeRoomName、/room/prohibitAddMember 等接口依赖 roomFlag 或 newFlag。

注意：

roomFlag 传错可能导致群其它状态错乱。
newFlag 应从群详情或群成员变动接口获取。
注意区分 roomFlag 与 roomNewFlag。
建议修改前读取群详情并记录原始值，便于回滚。

16.7 文件资源有效期

下载接口返回的临时云资源不是官方 CDN，通常 7-15 天不定期清理。业务系统如果需要长期保留，必须及时下载并转存。

17. 接口总览索引

/client/createClient：创建设备。
/client/restoreClient：恢复设备。
/client/stopClient：停用设备。
/login/getLoginQrcode：获取登录二维码。
/login/checkLoginQrCode：检测二维码状态。
/login/verifyLoginQrcode：验证 6 位登录码。
/login/manualLogin：免扫码登录。
/login/checkLogin：查询登录状态。

回调

/client/setCallback：设置 HTTP 回调地址。

消息

/msg/sendText：发送文本。
/msg/sendHyperText：发送混合文本。
/msg/sendImage：发送图片。
/msg/sendFile：发送文件。
/msg/sendVoice：发送语音。
/msg/sendVideo：发送视频。
/msg/sendLink：发送链接。
/msg/sendLocation：发送位置。
/msg/sendPersonalCard：发送名片。
/msg/sendWeapp：发送小程序。
/msg/sendFeedVideo：发送视频号。
/msg/sendGif：发送 GIF。
/msg/syncMsg：同步历史消息。
/msg/revokeMsg：撤回消息。
/msg/statusModify：修改消息/会话状态。
/msg/voiceToTextApply：语音转文字申请。
/msg/voiceToTextQuery：语音转文字查询。
/msg/sendGroupMsg：群发助手发送。
/msg/sendGroupMsgRule：群发规则查询。
/msg/sendGroupMsgStatus：群发状态查询。
/msg/roomTopMessageList：群置顶消息列表。
/msg/roomTopMessageSet：群置顶消息添加/移除。
/msg/syncCollectionMsg：收藏分页。
/msg/insertCollectionMsg：添加 GIF 表情收藏。

文件与媒体

/cloud/cdnBigUpload：本地文件上传。
/cloud/cdnBigUploadByUrl：URL 文件上传。
/cloud/cdnUploadByUrlAsync：企微文件异步 URL 上传。
/cloud/cdnBigFileUploadByUrlAsync：企微大文件异步 URL 上传。
/cloud/wxWorkDownload：企微文件下载。
/cloud/wxWorkDownloadAsync：企微文件异步下载。
/cloud/cdnBigFileDownloadByUrlAsync：企微大文件异步下载。
/cloud/wxDownload：个微文件下载。
/cloud/wxDownloadAsync：个微文件异步下载。
/cloud/cdnWxDownload：文件 CDN 转 URL。

联系人

/contact/getWxContactList：外部联系人分页。
/contact/getWxWorkContactList：内部联系人分页。
/contact/batchGetUserinfo：联系人详情批量查询。
/contact/searchContact：联系人搜索。
/contact/openid：联系人 OpenID 转换。
/contact/addSearchWxContact：添加个微联系人。
/contact/addSearchWxWorkContact：添加企微联系人。
/contact/addCardContact：通过名片添加联系人。
/contact/addRoomContact：添加群成员好友。
/contact/addDeletedContact：添加已删除联系人。
/contact/agreeContact：同意申请。
/contact/updateWxContact：更新外部联系人信息。
/contact/updateWxWorkContact：更新内部联系人信息。
/contact/deleteContact：删除联系人。

群

/room/createRoom：创建群。
/room/getRoomList：群分页。
/room/batchGetRoomDetail：群详情批量查询。
/room/getRoomIncrSync：群成员变动查询。
/room/getRoomQrCode：群二维码。
/room/openid：群 OpenID 转换。
/room/inviteRoomMember：邀请/添加成员。
/room/removeRoomMember：移除成员。
/room/agreeInviteByLink：通过链接接受群邀请。
/room/quitRoom：退群。
/room/dismissRoom：群解散。
/room/changeRoomMaster：转让群主。
/room/modifyRoomName：修改群名称。
/room/modifyRoomRemarkName：修改群备注。
/room/modifyRoomNotice：修改群公告。
/room/modifyRoomNickname：修改群内昵称。
/room/roomAddAdmin：添加群管理员。
/room/roomRemoveAdmin：取消群管理员。
/room/openInviteConfirm：开启群邀请确认。
/room/enableChangeRoomName：开启群改名。
/room/prohibitAddMember：禁止群成员互相添加。

会话

/session/getSessionPage：会话分页。
/session/getSessionList：会话组查询。
/session/setSessionCmd：会话组编辑。

朋友圈

/sns/upload：朋友圈文件上传。
/sns/postSns：发送朋友圈。
/sns/getSnsRecord：朋友圈列表分页。
/sns/getSnsDetail：朋友圈详情批量查询。
/sns/snsLike：点赞/取消赞。
/sns/snsComment：评论/追评。
/sns/deleteSnsComment：删除评论。
/sns/deleteSns：删除朋友圈。

个人

/user/getProfile：获取个人信息。
/user/setProfile：更新个人信息。
/user/getQrcodeCard：生成二维码。
/user/getCorpInfo：查询企业信息。
/user/logout：账号退出。

18. 推荐的知识库问答拆分维度

如果将本文档用于 RAG 知识库，建议按以下粒度切分：

通用调用规范：域名、入口、Header、请求结构、响应结构。

登录流程：设备创建、二维码登录、状态码、免扫码、恢复/停用。

回调结构：cmd 类型、账号状态、API 异步、系统消息、普通消息。

消息发送：每种消息类型单独切片，保留参数表和注意事项。

文件上传下载：同步/异步、企微/个微、大文件、fileType。

联系人管理：分页、详情、添加、更新、删除、OpenID。

群管理：查询、成员、资料、权限、flag 风险。

朋友圈：上传、发布、查询、互动、删除。

标签：标签分页、个人标签、客户标签。

业务场景：AI 客服、CRM 同步、群运营、朋友圈运营、文件归档。

建议每个切片保留：

接口 method。
请求入口 doApi 或 doFileApi。
必填参数。
参数枚举。
注意事项。
相关回调或前置接口。

19. 合规提醒

请勿将本服务用于违法用途（如广告骚扰、诈骗等）。违规使用将终止服务并可能配合相关部门处理。企业在接入前应结合自身业务场景建立权限控制、操作审计、客户授权、频率限制与风险拦截机制。