{ "openapi": "3.0.3", "info": { "title": "Eyun 企业微信 API", "version": "2026.09.11", "description": "Eyun 企业微信 API。全部 POST + JSON，请求头 Authorization: Bearer ，body 里的 appid 指定操作哪个实例。统一响应封套 {code,data,detail,message,time}，code=0 成功。" }, "servers": [ { "url": "{BASE_URL}/wx-api", "description": "接入地址在企业微信控制台应用凭证页查看", "variables": { "BASE_URL": { "default": "https://your-endpoint.example", "description": "接入地址在企业微信控制台应用凭证页查看" } } } ], "tags": [ { "name": "登录", "description": "login 分类" }, { "name": "消息", "description": "message 分类" }, { "name": "联系人", "description": "contact 分类" }, { "name": "群", "description": "room 分类" }, { "name": "客户朋友圈", "description": "friend 分类" }, { "name": "CDN 文件", "description": "cdn 分类" }, { "name": "标签", "description": "label 分类" }, { "name": "个人信息", "description": "personal 分类" }, { "name": "回调配置(Webhook)", "description": "客户用 App Token 自助设置回调地址(Webhook)——系统管理 API,非服务包接口" }, { "name": "回调(Webhook)", "description": "长链回调推送报文(非服务包接口,文档参考)" } ], "components": { "securitySchemes": { "AppToken": { "type": "http", "scheme": "bearer", "description": "App Token（Authorization: Bearer ，App Token 形如 eyk_xxxx）；指定实例在 body 传 appid" } } }, "security": [ { "AppToken": [] } ], "paths": { "/api/login/getQr": { "post": { "tags": [ "登录" ], "summary": "获取二维码", "operationId": "login_getQr", "description": "【对外网关行为】① 不带 appid 自动创建设备,响应 data.appid 即新实例标识;带 appid 则复用。② 代理三选一 region(省份 1-31)/ socks5(自定义)/ aid(6 位),必须使用;三者都不填时:已有 appid 回退其上次代理,新建 appid 报 proxy_required。③ 解析出的代理会缓存到该 appid,后续敏感接口自动取用。 | 【2026-09-06 实测】响应 = {imageBase64(JPEG 图片 base64), uuid, refreshInterval:600};checkQr 需要用到本接口返回的 uuid。\n\n> **对外网关(/wx-api)行为**:① 不带 `appid` 自动创建设备并在响应 `data.appid` 返回;带 `appid` 则复用。② 代理三选一 `region`(省份 1-31)/ `socks5` / `aid`(6 位),**必须使用**;三者都不填时:已有 appid 回退其上次代理,新建 appid 则报 `proxy_required`。③ 解析出的代理会缓存到该 appid,后续敏感接口自动取用。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备 appid;**不传则自动创建设备**" }, "region": { "type": "string", "description": "地区代理:省份编号 1-31(与 socks5/aid 三选一)" }, "socks5": { "type": "string", "description": "自定义 socks5 代理地址(与 region/aid 三选一)" }, "aid": { "type": "string", "description": "aid 代理:6 位数字(与 region/socks5 三选一)" } } }, "example": { "region": "7" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "properties": { "imageBase64": { "type": "string", "description": "登录二维码图片的 JPEG base64(约 57KB);前端用 `data:image/jpeg;base64,<该串>` 直接渲染" }, "uuid": { "type": "string", "description": "二维码会话标识(getQr 返回,checkQr 必带)" }, "refreshInterval": { "type": "integer", "format": "int64", "description": "二维码有效期 / 刷新间隔,单位秒;`600` = 10 分钟,超时需重新 getQr" }, "appid": { "type": "string", "description": "设备 appid(自动创建时在此返回)" } }, "description": "业务数据(结构以实测为准)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": { "imageBase64": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDABQODxIP...(JPEG base64,约 57KB)", "uuid": "61AC3F0E49D4A74A3CF5A3D4A53C6099", "refreshInterval": 600, "appid": "we_自动创建或复用的设备appid" }, "detail": "", "message": "ok", "time": "2026-09-06 11:11:26" } } } } } } }, "/api/login/checkQr": { "post": { "tags": [ "登录" ], "summary": "检测二维码", "operationId": "login_checkQr", "description": "【对外网关行为】无需传代理(系统自动取用该 appid 缓存代理);**无需传 callbackUrl**——长链回调地址由系统维护并自动注入,系统收到回调后按你配置的 Webhook 转发推送。 | 【2026-09-06 真人扫码实测,status 全枚举】0=未扫码(data 仅 uuid+status);已扫待确认=1/6 之一(控制台映射命中,原始样本被轮转覆盖,具体值待复扫回补);10=需验证码(data 增 nickName/avatarUrl/corpUserId/corpId/corpLogoUrl);2=登录成功(示例即,另含 authId/nonceKey/deviceUuid/scannerNonce/WxUserProfile)。不带 uuid 报 -12006|get expried data fail。 | 轮询调用,直到登录成功。文档示例给的是二维码过期时的错误响应(code -1, message '-12007|get expired data empty'),此时应重新 getQr。\n\n> **对外网关(/wx-api)行为**:无需传代理(自动取用缓存);**无需传 `callbackUrl`**——长链回调地址由系统维护并自动注入,系统收到回调后按你配置的 Webhook 转发推送。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "uuid": { "type": "string", "description": "[string] getQr 返回的二维码 uuid" }, "pushHistory": { "type": "boolean", "description": "[bool] 是否推送历史消息" } }, "required": [ "uuid", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "uuid": "68EF33CF8D86CBC1D9214DCA3AD6B04C", "pushHistory": false } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "description": "二维码会话标识(getQr 返回,checkQr 必带)" }, "authId": { "type": "integer", "format": "int64", "description": "企业对本设备的授权 id(int64)" }, "corpId": { "type": "integer", "format": "int64", "description": "所属企业唯一 id(int64)" }, "status": { "type": "integer", "format": "int64", "description": "状态编码(具体含义随所在对象与接口:如登录态、在线态、投递态等,详见对应接口)" }, "nickName": { "type": "string", "description": "昵称" }, "nonceKey": { "type": "string", "description": "登录随机密钥(凭证,勿外泄)" }, "avatarUrl": { "type": "string", "description": "头像 url" }, "corpUserId": { "type": "integer", "format": "int64", "description": "用户在企业内的成员 id(int64)" }, "deviceUuid": { "type": "string", "description": "设备唯一标识(登录凭证)" }, "corpLogoUrl": { "type": "string", "description": "企业 logo url" }, "scannerNonce": { "type": "string", "description": "扫码方随机串(登录凭证)" }, "WxUserProfile": { "type": "object", "properties": { "avatarUrl": { "type": "string", "description": "头像 url" }, "wechatName": { "type": "string", "description": "微信昵称" } }, "description": "扫码者的微信侧资料(头像/昵称等)" } }, "description": "业务数据(结构以实测为准)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": { "uuid": "4BB5…FE7B", "authId": 2251801417098298, "corpId": 1970324965569447, "status": 2, "nickName": "哈**", "nonceKey": "J5L0…(脱敏)", "avatarUrl": "https://wework.qpic.cn/wwpic3az/373744_…/0", "corpUserId": 1688857562919230, "deviceUuid": "52be…(脱敏)", "corpLogoUrl": "https://wework.qpic.cn/wwpic3az/875652_…/0", "scannerNonce": "oT4e…(脱敏)", "WxUserProfile": { "avatarUrl": "https://thirdwx.qlogo.cn/…", "wechatName": "…" } }, "detail": "", "message": "ok", "time": "2026-09-06 11:51:31" } } } } } } }, "/api/login/submitQrCode": { "post": { "tags": [ "登录" ], "summary": "提交验证码", "operationId": "login_submitQrCode", "description": "【2026-09-06 实测】提交成功返回空 data;随后 checkQr 由 10 转 2(约 6 秒)。代理由系统自动取用缓存,无需传。 | 扫码后企微要求输入验证码时调用;提交后继续 checkQr 轮询直到成功。\n\n> **对外网关(/wx-api)行为**:无需传代理,网关自动取用缓存代理。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "code": { "type": "string", "description": "[string] 手机端显示的 6 位验证码" }, "uuid": { "type": "string", "description": "[string] getQr 返回的 uuid" } }, "required": [ "code", "uuid", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "code": "993416", "uuid": "F6FFE8CA3CFA8633EECF5F5A25600FEE" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "properties": {}, "description": "业务数据(结构以实测为准)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-06 11:51:25" } } } } } } }, "/api/login/reconnect": { "post": { "tags": [ "登录" ], "summary": "断线重连", "operationId": "login_reconnect", "description": "收到回调 GapClosed code -11001 时调用,判断账号是否仍在线并恢复(长链本身由系统维护,客户只需按需调本接口触发恢复)。代理由系统按实例缓存自动取用,无需再传。\n\n> **对外网关(/wx-api)行为**:无需传代理,网关自动取用缓存代理。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" } }, "required": [ "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/login/logout": { "post": { "tags": [ "登录" ], "summary": "退出登录", "operationId": "login_logout", "description": "主动退出企微登录。\n\n**安全级别**: destructive(执行前需二次确认 confirm)", "x-safety": "destructive", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" } }, "required": [ "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/message/sync": { "post": { "tags": [ "消息" ], "summary": "同步消息", "operationId": "message_sync", "description": "【2026-09-06 实测】响应 = data.{count, isEnd, list[]};消息对象含 int64 id/syncKey;示例裁剪至 1 项。 | 主动拉取消息;正常情况下消息由长链回调 Msg 事件推送,本接口用于补拉。\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "limit": { "type": "integer", "format": "int64", "description": "[int] 拉取条数" }, "syncKey": { "type": "integer", "format": "int64", "description": "[int] 上次同步游标;首次可传 0" } }, "required": [ "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "limit": 100, "syncKey": 15875106 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "properties": { "count": { "type": "integer", "format": "int64", "description": "本批返回条数" }, "isEnd": { "type": "boolean", "description": "是否已到末页" }, "list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "记录/文件业务标识" }, "syncKey": { "type": "integer", "format": "int64", "description": "同步游标;增量拉取的断点" }, "messageType": { "type": "integer", "format": "int64", "description": "消息大类(0 普通/3 系统通知/103 自身操作)" }, "fromUserId": { "type": "integer", "format": "int64", "description": "发送方 id(uin);群消息里是真实发送成员" }, "toUserId": { "type": "integer", "format": "int64", "description": "接收方 id(uin),通常是本账号" }, "roomId": { "type": "integer", "format": "int64", "description": "群会话 id(int64);非群消息为 0" }, "contentType": { "type": "integer", "format": "int64", "description": "消息类型码(0 文本/14 图片/23 视频…)" }, "sendTime": { "type": "integer", "format": "int64", "description": "发送时间(Unix 秒)" }, "appInfo": { "type": "string", "description": "企微内部透传串(base64);群发/待发送场景需回填,业务方不必解析" }, "senderName": { "type": "string", "description": "发送者昵称(可能为空)" }, "content": { "type": "object", "properties": { "msgType": { "type": "integer", "format": "int64", "description": "消息类型码,决定 content 形状(见回调大全)" }, "hex": { "type": "string" } }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" }, "extraData": { "type": "string", "description": "企微内部透传(新协议为 base64 字符串;老协议曾为字符串数组);业务方不解析" }, "flag": { "type": "integer", "format": "int64", "description": "消息标志位 / 设备信息 / 摘要;观测到 `flag` 取 0 或 16777216,`summary` 常为空。精确含义待确认" }, "devInfo": { "type": "integer", "format": "int64", "description": "消息标志位 / 设备信息 / 摘要;观测到 `flag` 取 0 或 16777216,`summary` 常为空。精确含义待确认" }, "summary": { "type": "string", "description": "消息标志位 / 设备信息 / 摘要;观测到 `flag` 取 0 或 16777216,`summary` 常为空。精确含义待确认" } }, "description": "消息对象数组" }, "description": "消息对象数组" }, "syncKey": { "type": "integer", "format": "int64", "description": "同步游标;增量拉取的断点" } }, "description": "业务数据(结构以实测为准)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": { "count": 935, "isEnd": false, "list": [ { "id": 1136157, "syncKey": 12269915, "messageType": 3, "fromUserId": 10120, "toUserId": 0, "roomId": 10120, "contentType": 31, "sendTime": 1780878274, "appInfo": "wwdailyindustrynews_appinfo_1780848000", "senderName": "", "content": { "msgType": 31, "hex": "0ae9020a4be5908ce4ba8be4bbace59ca8e79c8b..." }, "extraData": "4kA7CAISBBiCgAgSBBiBgAgSDQoHNC4xLjIuMBiCgAQSDQoHNC4xLjIuMBiBgAQSDQoHNC4xLjIuMBiDgAiqvgFlCiCbvYaYXnr1cxYbf1AK02kzjyx7j/GoOpEMTBH5VytegRAfGj8IwpeY0QYQAhomd3dkYWlseWluZHVzdHJ5bmV3c19hcHBpbmZvXzE3ODA4NDgwMDAiAhAAML7+6+SUgIADOAE=", "flag": 0, "devInfo": 0, "summary": "" } ], "syncKey": 12370562 }, "detail": "", "message": "ok", "time": "2026-09-06 11:12:58" } } } } } } }, "/api/message/sendText": { "post": { "tags": [ "消息" ], "summary": "发送文本消息", "operationId": "message_sendText", "description": "【2026-09-06 实测】conversationId 必须是 JSON number——传字符串报 cannot unmarshal string into uint64;响应为完整消息对象。 |\n\n> 【坑】conversationId 必须传 JSON number 不能字符串(Go 严格解码);自聊要用本账号 uin 作目标,不能用伪房间 roomId(报 -3020)。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "conversationId": { "type": "integer", "format": "int64", "description": "[int64] 会话 id:联系人 userId 或群 roomId" }, "content": { "type": "string", "description": "[string] 文本内容" } }, "required": [ "conversationId", "content", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "conversationId": 1688855874759204, "content": "示例文本消息" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "记录/文件业务标识" }, "syncKey": { "type": "integer", "format": "int64", "description": "同步游标;增量拉取的断点" }, "messageType": { "type": "integer", "format": "int64", "description": "消息大类(0 普通/3 系统通知/103 自身操作)" }, "fromUserId": { "type": "integer", "format": "int64", "description": "发送方 id(uin);群消息里是真实发送成员" }, "toUserId": { "type": "integer", "format": "int64", "description": "接收方 id(uin),通常是本账号" }, "roomId": { "type": "integer", "format": "int64", "description": "群会话 id(int64);非群消息为 0" }, "contentType": { "type": "integer", "format": "int64", "description": "消息类型码(0 文本/14 图片/23 视频…)" }, "sendTime": { "type": "integer", "format": "int64", "description": "发送时间(Unix 秒)" }, "appInfo": { "type": "string", "description": "企微内部透传串(base64);群发/待发送场景需回填,业务方不必解析" }, "senderName": { "type": "string", "description": "发送者昵称(可能为空)" }, "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "integer", "format": "int64", "description": "类型编码(具体含义随所在对象:成员/部门、图片/视频、节点类型等,详见对应接口)" }, "text": { "type": "string", "description": "type 0/3 的文本内容" } }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" }, "extraData": { "type": "string", "description": "企微内部透传(新协议为 base64 字符串;老协议曾为字符串数组);业务方不解析" }, "flag": { "type": "integer", "format": "int64", "description": "消息标志位 / 设备信息 / 摘要;观测到 `flag` 取 0 或 16777216,`summary` 常为空。精确含义待确认" }, "devInfo": { "type": "integer", "format": "int64", "description": "消息标志位 / 设备信息 / 摘要;观测到 `flag` 取 0 或 16777216,`summary` 常为空。精确含义待确认" }, "summary": { "type": "string", "description": "消息标志位 / 设备信息 / 摘要;观测到 `flag` 取 0 或 16777216,`summary` 常为空。精确含义待确认" } }, "description": "业务数据(结构以实测为准)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": { "id": 1145139, "messageType": 0, "contentType": 0, "fromUserId": 1688850000000001, "toUserId": 7881300000000002, "sendTime": 1788664632, "content": [ { "type": 0, "text": "示例文本消息" } ] }, "detail": "", "message": "ok", "time": "2026-09-06 11:17:13" } } } } } } }, "/api/message/sendRichText": { "post": { "tags": [ "消息" ], "summary": "发送带富文本消息", "operationId": "message_sendRichText", "description": "群聊 @ 功能通过 type 5 实现。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "conversationId": { "type": "integer", "format": "int64", "description": "会话 id(int64),发送时必须传 JSON number 不能字符串" }, "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "integer", "format": "int64", "description": "类型编码(具体含义随所在对象:成员/部门、图片/视频、节点类型等,详见对应接口)" }, "text": { "type": "string", "description": "type 0/3 的文本内容" } }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" } }, "required": [ "conversationId", "content", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "conversationId": 1688855874759204, "content": [ { "type": 0, "text": "你好 " }, { "type": 3, "text": "[愉快]" }, { "type": 5 }, { "type": 5, "userId": 1688855319807969 }, { "type": 0, "text": " 测试一下" } ] } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/message/sendVoice": { "post": { "tags": [ "消息" ], "summary": "发送语音消息", "operationId": "message_sendVoice", "description": "语音文件需为 silk 格式,先经 /api/cdn/uploadFile 上传。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "conversationId": { "type": "integer", "format": "int64", "description": "会话 id(int64),发送时必须传 JSON number 不能字符串" }, "content": { "type": "object", "properties": { "id": { "type": "string", "description": "[string] /api/cdn/uploadFile 返回的 fileId(silk 语音)" }, "url": { "type": "string", "description": "链接 / 资源地址" }, "size": { "type": "integer", "format": "int64", "description": "文件字节数" }, "voiceTime": { "type": "integer", "format": "int64", "description": "[int] 语音秒数" }, "aesKey": { "type": "string", "description": "AES 下载解密密钥;CDN 存的是加密字节,下载后用它解密" }, "md5": { "type": "string", "description": "文件内容 MD5,收发方一致性校验" } }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" } }, "required": [ "conversationId", "content", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "conversationId": 0, "content": { "id": "上传返回的 fileId", "url": "", "size": 12216, "voiceTime": 5, "aesKey": "上传返回的 aesKey", "md5": "上传返回的 fileMd5" } } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/message/sendImage": { "post": { "tags": [ "消息" ], "summary": "发送图片消息", "operationId": "message_sendImage", "description": "【2026-09-06 实测】响应为完整消息对象(contentType:14 = 图片),与 sendText 同构;content 即 uploadImage data 原样回显。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "conversationId": { "type": "integer", "format": "int64", "description": "会话 id(int64),发送时必须传 JSON number 不能字符串" }, "content": { "type": "object", "properties": { "id": { "type": "string", "description": "记录/文件业务标识" }, "size": { "type": "integer", "format": "int64", "description": "文件字节数" }, "width": { "type": "integer", "format": "int64", "description": "宽(像素)" }, "height": { "type": "integer", "format": "int64", "description": "高(像素)" }, "aesKey": { "type": "string", "description": "AES 下载解密密钥;CDN 存的是加密字节,下载后用它解密" }, "md5": { "type": "string", "description": "文件内容 MD5,收发方一致性校验" }, "midImageFileSize": { "type": "integer", "format": "int64", "description": "中图字节数" }, "thumbFileSize": { "type": "integer", "format": "int64", "description": "缩略图字节数" }, "thumbWidth": { "type": "integer", "format": "int64", "description": "缩略图宽" }, "thumbHeight": { "type": "integer", "format": "int64", "description": "缩略图高" }, "thumbMd5": { "type": "string", "description": "缩略图 MD5" } }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" } }, "required": [ "conversationId", "content", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "conversationId": 7881301709020163, "content": { "id": "", "size": 10528, "width": 284, "height": 177, "aesKey": "ef9c3132a4790b0b6c711198e355823e", "md5": "065954fddfa288194a56407d279b4aac", "midImageFileSize": 11338, "thumbFileSize": 11338, "thumbWidth": 240, "thumbHeight": 149, "thumbMd5": "16a7677492f36683af5c3eef54d939bd" } } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "记录/文件业务标识" }, "syncKey": { "type": "integer", "format": "int64", "description": "同步游标;增量拉取的断点" }, "messageType": { "type": "integer", "format": "int64", "description": "消息大类(0 普通/3 系统通知/103 自身操作)" }, "fromUserId": { "type": "integer", "format": "int64", "description": "发送方 id(uin);群消息里是真实发送成员" }, "toUserId": { "type": "integer", "format": "int64", "description": "接收方 id(uin),通常是本账号" }, "roomId": { "type": "integer", "format": "int64", "description": "群会话 id(int64);非群消息为 0" }, "contentType": { "type": "integer", "format": "int64", "description": "消息类型码(0 文本/14 图片/23 视频…)" }, "sendTime": { "type": "integer", "format": "int64", "description": "发送时间(Unix 秒)" }, "appInfo": { "type": "string", "description": "企微内部透传串(base64);群发/待发送场景需回填,业务方不必解析" }, "senderName": { "type": "string", "description": "发送者昵称(可能为空)" }, "content": { "type": "object", "properties": { "id": { "type": "string", "description": "记录/文件业务标识" }, "size": { "type": "integer", "format": "int64", "description": "文件字节数" }, "width": { "type": "integer", "format": "int64", "description": "宽(像素)" }, "height": { "type": "integer", "format": "int64", "description": "高(像素)" }, "aesKey": { "type": "string", "description": "AES 下载解密密钥;CDN 存的是加密字节,下载后用它解密" }, "md5": { "type": "string", "description": "文件内容 MD5,收发方一致性校验" }, "midImageFileSize": { "type": "integer", "format": "int64", "description": "中图字节数" }, "thumbFileSize": { "type": "integer", "format": "int64", "description": "缩略图字节数" }, "thumbWidth": { "type": "integer", "format": "int64", "description": "缩略图宽" }, "thumbHeight": { "type": "integer", "format": "int64", "description": "缩略图高" }, "thumbMd5": { "type": "string", "description": "缩略图 MD5" } }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" }, "extraData": { "type": "string", "description": "企微内部透传(新协议为 base64 字符串;老协议曾为字符串数组);业务方不解析" }, "flag": { "type": "integer", "format": "int64", "description": "消息标志位 / 设备信息 / 摘要;观测到 `flag` 取 0 或 16777216,`summary` 常为空。精确含义待确认" }, "devInfo": { "type": "integer", "format": "int64", "description": "消息标志位 / 设备信息 / 摘要;观测到 `flag` 取 0 或 16777216,`summary` 常为空。精确含义待确认" }, "summary": { "type": "string", "description": "消息标志位 / 设备信息 / 摘要;观测到 `flag` 取 0 或 16777216,`summary` 常为空。精确含义待确认" } }, "description": "业务数据(结构以实测为准)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": { "id": 1145149, "syncKey": 12470069, "messageType": 0, "fromUserId": 1688855440457534, "toUserId": 1688855655434798, "roomId": 0, "contentType": 14, "sendTime": 1788666063, "appInfo": "CAQQz8Hz…", "senderName": "陈**", "content": { "id": "3068…0400", "size": 3788, "width": 200, "height": 120, "aesKey": "a80e52a7191df0a1c2aac34076898df4", "md5": "2228e4e55326a9e5c5478b40a22499d0", "midImageFileSize": 3562, "thumbFileSize": 3562, "thumbWidth": 200, "thumbHeight": 120, "thumbMd5": "9736a9f86ba94311a28e1b4ed7115a5a" }, "extraData": "…", "flag": 16777216, "devInfo": 0, "summary": "" }, "detail": "", "message": "ok", "time": "2026-09-06 11:41:03" } } } } } } }, "/api/message/sendVideo": { "post": { "tags": [ "消息" ], "summary": "发送视频消息", "operationId": "message_sendVideo", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "conversationId": { "type": "integer", "format": "int64", "description": "会话 id(int64),发送时必须传 JSON number 不能字符串" }, "content": { "type": "object", "properties": { "id": { "type": "string", "description": "取自 /api/cdn/uploadVideo" }, "size": { "type": "integer", "format": "int64", "description": "取自 /api/cdn/uploadVideo" }, "duration": { "type": "integer", "format": "int64", "description": "[int] 视频秒数" }, "width": { "type": "integer", "format": "int64", "description": "宽(像素)" }, "height": { "type": "integer", "format": "int64", "description": "高(像素)" }, "thumbUrl": { "type": "string", "description": "[string] 封面图 url" }, "aesKey": { "type": "string", "description": "取自 /api/cdn/uploadVideo" }, "md5": { "type": "string", "description": "取自 /api/cdn/uploadVideo" } }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" } }, "required": [ "conversationId", "content", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "conversationId": 10786447466811918, "content": { "id": "", "size": 873163, "duration": 4, "width": 720, "height": 1280, "thumbUrl": "https://wework.qpic.cn/wwpic3az/827551_HeHFDfI8SsyXxFm_1785915262", "aesKey": "7e96d1b925cd0b8401d8350e815d13c7", "md5": "e6c6f697cd8f9be46d8890d9b985320c" } } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/message/sendFile": { "post": { "tags": [ "消息" ], "summary": "发送文件消息", "operationId": "message_sendFile", "description": "普通文件(小文件);大文件走 sendBigFile。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "conversationId": { "type": "integer", "format": "int64", "description": "会话 id(int64),发送时必须传 JSON number 不能字符串" }, "content": { "type": "object", "properties": { "id": { "type": "string", "description": "取自 /api/cdn/uploadFile" }, "name": { "type": "string", "description": "[string] 文件名(含扩展名)" }, "url": { "type": "string", "description": "链接 / 资源地址" }, "size": { "type": "integer", "format": "int64", "description": "取自 /api/cdn/uploadFile" }, "aesKey": { "type": "string", "description": "取自 /api/cdn/uploadFile" }, "md5": { "type": "string", "description": "取自 /api/cdn/uploadFile" } }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" } }, "required": [ "conversationId", "content", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "conversationId": 10786447466811918, "content": { "id": "", "name": "wework_voice_5s.silk", "url": "", "size": 12216, "aesKey": "0c985abaf66a93d054847faf821868db", "md5": "f6073d7c966718c256fc3fbf351915aa" } } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/message/sendBigFile": { "post": { "tags": [ "消息" ], "summary": "发送大文件", "operationId": "message_sendBigFile", "description": "先 /api/cdn/uploadBigFile(异步),等大文件上传完成推送后再调本接口。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "conversationId": { "type": "integer", "format": "int64", "description": "会话 id(int64),发送时必须传 JSON number 不能字符串" }, "content": { "type": "object", "properties": { "id": { "type": "string", "description": "取自大文件上传完成推送的 `content`，见[回调字典 · 大文件上传完成](/wecom/webhook/callback#大文件上传完成)（id 以 `*1*` 开头）" }, "name": { "type": "string", "description": "取自大文件上传完成推送的 `content`，见[回调字典 · 大文件上传完成](/wecom/webhook/callback#大文件上传完成)" }, "url": { "type": "string", "description": "链接 / 资源地址" }, "size": { "type": "integer", "format": "int64", "description": "取自大文件上传完成推送的 `content`，见[回调字典 · 大文件上传完成](/wecom/webhook/callback#大文件上传完成)" }, "aesKey": { "type": "string", "description": "AES 下载解密密钥;CDN 存的是加密字节,下载后用它解密" }, "md5": { "type": "string", "description": "取自大文件上传完成推送的 `content`，见[回调字典 · 大文件上传完成](/wecom/webhook/callback#大文件上传完成)" } }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" } }, "required": [ "conversationId", "content", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "conversationId": 10786447466811918, "content": { "id": "*1*", "name": "完整pb数据.txt", "url": "", "size": 45675521, "aesKey": "", "md5": "6cfb4f980bcf246507fdc965d3806b43" } } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/message/sendLink": { "post": { "tags": [ "消息" ], "summary": "发送链接卡片消息(包含视频号)", "operationId": "message_sendLink", "description": "【2026-09-11 实测】响应只回显 imageUrl/title/description,不回显 linkUrl。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "conversationId": { "type": "integer", "format": "int64", "description": "会话 id(int64),发送时必须传 JSON number 不能字符串" }, "content": { "type": "object", "properties": { "linkUrl": { "type": "string", "description": "[string] 普通链接卡片四要素" }, "imageUrl": { "type": "string", "description": "[string] 普通链接卡片四要素" }, "title": { "type": "string", "description": "[string] 普通链接卡片四要素" }, "description": { "type": "string", "description": "[string] 普通链接卡片四要素" }, "sph_feed_h5_message": { "type": "object", "properties": { "feedType": { "type": "integer", "format": "int64", "description": "朋友圈动态类型" }, "coverUrl": { "type": "string", "description": "封面图 url" }, "avatar": { "type": "string", "description": "头像 url" }, "nickname": { "type": "string", "description": "我在本群的新昵称" }, "desc": { "type": "string" }, "url": { "type": "string", "description": "链接 / 资源地址" }, "exportNewUrl": { "type": "string" }, "useH5": { "type": "boolean" } }, "description": "[object] 视频号卡片专用;其中 coverUrl/avatar/nickname/desc/url/exportNewUrl 为 base64 编码字符串,feedType 4,useH5 true" } }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" } }, "required": [ "conversationId", "content", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "conversationId": 10786447466811918, "content": { "linkUrl": "https://example.com/page", "imageUrl": "https://example.com/cover.jpg", "title": "卡片标题", "description": "卡片描述", "sph_feed_h5_message": { "feedType": 4, "coverUrl": "", "avatar": "", "nickname": "", "desc": "", "url": "", "exportNewUrl": "", "useH5": true } } } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/message/sendNameCard": { "post": { "tags": [ "消息" ], "summary": "发送名片消息", "operationId": "message_sendNameCard", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "conversationId": { "type": "integer", "format": "int64", "description": "[int64] 发送到哪个会话" }, "cardUserId": { "type": "integer", "format": "int64", "description": "[int64] 名片对应的用户 id" } }, "required": [ "conversationId", "cardUserId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "conversationId": 10786447466811918, "cardUserId": 1688855319807969 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/message/sendGif": { "post": { "tags": [ "消息" ], "summary": "发送GIF消息", "operationId": "message_sendGif", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "conversationId": { "type": "integer", "format": "int64", "description": "会话 id(int64),发送时必须传 JSON number 不能字符串" }, "content": { "type": "object", "properties": { "url": { "type": "string", "description": "GIF 表情信息(通常来自收到的消息)" }, "thumbUrl": { "type": "string", "description": "GIF 表情信息(通常来自收到的消息)" }, "md5": { "type": "string", "description": "GIF 表情信息(通常来自收到的消息)" }, "size": { "type": "integer", "format": "int64", "description": "GIF 表情信息(通常来自收到的消息)" }, "width": { "type": "integer", "format": "int64", "description": "GIF 表情信息(通常来自收到的消息)" }, "height": { "type": "integer", "format": "int64", "description": "GIF 表情信息(通常来自收到的消息)" }, "name": { "type": "string", "description": "GIF 表情信息(通常来自收到的消息)" } }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" } }, "required": [ "conversationId", "content", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "conversationId": 10786447466811918, "content": { "url": "http://p.qpic.cn/pic_wework/1802732579/f2f4.../0", "thumbUrl": "http://p.qpic.cn/pic_wework/1802732579/3036.../0", "md5": "48BC89479099BDEB9965CB93C8884FB8", "size": 45754, "width": 240, "height": 240, "name": "辛苦了" } } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/message/sendLocation": { "post": { "tags": [ "消息" ], "summary": "发送位置消息", "operationId": "message_sendLocation", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "conversationId": { "type": "integer", "format": "int64", "description": "会话 id(int64),发送时必须传 JSON number 不能字符串" }, "content": { "type": "object", "properties": { "longitude": { "type": "number", "description": "[float] 经纬度" }, "latitude": { "type": "number", "description": "[float] 经纬度" }, "address": { "type": "string", "description": "[string] 地址与标题" }, "title": { "type": "string", "description": "[string] 地址与标题" } }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" } }, "required": [ "conversationId", "content", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "conversationId": 10786447466811918, "content": { "longitude": 121.12781, "latitude": 31.148475, "address": "上海市青浦区桂花园(外青松公路东100米)", "title": "青浦区桂花园(外青松公路东100米)" } } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/message/sendMiniProgram": { "post": { "tags": [ "消息" ], "summary": "发送小程序", "operationId": "message_sendMiniProgram", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "conversationId": { "type": "integer", "format": "int64", "description": "会话 id(int64),发送时必须传 JSON number 不能字符串" }, "content": { "type": "object", "properties": { "title": { "type": "string", "description": "标题" }, "miniProgramDetails": { "type": "object", "properties": { "username": { "type": "string", "description": "[string] 小程序信息" }, "appId": { "type": "string", "description": "[string] 小程序信息" }, "path": { "type": "string", "description": "[string] 小程序信息" }, "coverUrl": { "type": "string", "description": "封面图 url" }, "title": { "type": "string", "description": "[string] 小程序信息" }, "appName": { "type": "string", "description": "[string] 小程序信息" }, "fallbackUrl": { "type": "string", "description": "[string] 小程序信息" }, "coverFileId": { "type": "string", "description": "封面图需先 /api/cdn/uploadImage" }, "coverMd5": { "type": "string", "description": "封面图需先 /api/cdn/uploadImage" }, "coverAesKey": { "type": "string", "description": "封面图需先 /api/cdn/uploadImage" }, "coverSize": { "type": "integer", "format": "int64", "description": "封面图需先 /api/cdn/uploadImage" }, "coverWidth": { "type": "integer", "format": "int64", "description": "封面图需先 /api/cdn/uploadImage" }, "coverHeight": { "type": "integer", "format": "int64", "description": "封面图需先 /api/cdn/uploadImage" } }, "description": "小程序详情(内含 appId/path/封面等)" } }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" } }, "required": [ "conversationId", "content", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "conversationId": 7881301709020163, "content": { "title": "示例小程序", "miniProgramDetails": { "username": "gh_f9d9fca26a50@app", "appId": "<小程序 appId>", "path": "pages/tabBar/index/index.html", "coverUrl": "http://mmbiz.qpic.cn/.../640", "title": "示例小程序", "appName": "示例小程序", "fallbackUrl": "https://mp.weixin.qq.com/mp/waerrpage?appid=<小程序 appId>&type=upgrade&upgradetype=3#wechat_redirect", "coverFileId": "", "coverMd5": "961aa29ebd964455b22ecfaa691924d7", "coverAesKey": "caf54890e1a4f45b072e64db3d265fe7", "coverSize": 57102, "coverWidth": 500, "coverHeight": 400 } } } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/message/revoke": { "post": { "tags": [ "消息" ], "summary": "撤回消息", "operationId": "message_revoke", "description": "\n\n**安全级别**: destructive(执行前需二次确认 confirm)", "x-safety": "destructive", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "conversationId": { "type": "integer", "format": "int64", "description": "会话 id(int64),发送时必须传 JSON number 不能字符串" }, "serverMsgId": { "type": "integer", "format": "int64", "description": "[int64] 消息的服务端 id(回调 Msg 事件的 id)" } }, "required": [ "serverMsgId", "appid", "conversationId" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "conversationId": 1970325823022815, "serverMsgId": 1001469 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/message/getMaterialList": { "post": { "tags": [ "消息" ], "summary": "群发助手-获取素材库列表", "operationId": "message_getMaterialList", "description": "\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "nextPageStr": { "type": "string", "description": "[string] 翻页游标,首页传空" } }, "required": [ "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "nextPageStr": "" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/message/groupSend": { "post": { "tags": [ "消息" ], "summary": "群发助手-群发", "operationId": "message_groupSend", "description": "【2026-09-11 实测】**立即发送**,返回 `data.msgId`;发出的记录直接出现在 getGroupSendRecord(`id == msgId`),**不进** getPendingGroupSendList 队列 —— getPendingGroupSendList/groupSendPending 是另一套独立机制,不是本接口的后续。实测用一次性自建空群做 receiver 验证(customerGroup=true)。\n\n**安全级别**: write(执行前需二次确认 confirm)", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "customerGroup": { "type": "boolean", "description": "[bool] true=群发到客户群(receiverList 只能是群 id);false=群发到客户(receiverList 只能是客户 id),二者不能混" }, "contentList": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "integer", "format": "int64", "description": "消息类型码(0 文本/14 图片/23 视频…)" }, "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "integer", "format": "int64", "description": "类型编码(具体含义随所在对象:成员/部门、图片/视频、节点类型等,详见对应接口)" }, "text": { "type": "string", "description": "type 0/3 的文本内容" } }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" } }, "description": "素材内容片段(文案 + 附件)" }, "description": "素材内容片段(文案 + 附件)" }, "receiverList": { "type": "array", "items": { "type": "integer", "format": "int64", "description": "接收者 id 列表(客户 id 或群 id,与 customerGroup 对应)" }, "description": "[int64[]] 接收者 id 列表" }, "materialId": { "type": "integer", "format": "int64", "description": "[int64] 素材库 id;不是素材库内容时传 0" } }, "required": [ "customerGroup", "receiverList", "materialId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "customerGroup": true, "contentList": [ { "contentType": 0, "content": [ { "type": 3, "text": "[撇嘴]" }, { "type": 0, "text": "企业" } ] }, { "contentType": 14, "content": { "id": "", "size": 570260, "width": 828, "height": 1792, "aesKey": "9cf6...", "md5": "f6e0..." } }, { "contentType": 22, "content": { "id": "*1*<大文件 id>", "size": 285357, "duration": 2, "width": 1280, "height": 720, "thumbUrl": "https://wework.qpic.cn/...", "md5": "9915..." } }, { "contentType": 20, "content": {} } ], "receiverList": [ 10710637461658379 ], "materialId": 117159486110430465 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "properties": { "msgId": { "type": "integer", "format": "int64", "description": "下一页起始 msgId" } }, "description": "业务数据(结构以实测为准)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": { "msgId": 117252339567559381 }, "detail": "", "message": "ok", "time": "2026-09-11 20:20:00" } } } } } } }, "/api/message/getPendingGroupSendList": { "post": { "tags": [ "消息" ], "summary": "群发助手-获取待发送列表", "operationId": "message_getPendingGroupSendList", "description": "【2026-09-11 实测】待发送队列(与 groupSend 独立);本号实测为空 `list:null`。groupSend 不会往这里塞。\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" } }, "required": [ "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "是否还有更多" }, "list": { "nullable": true, "description": "消息对象数组" }, "nextKey": { "type": "object", "properties": { "msgId": { "type": "integer", "format": "int64", "description": "下一页起始 msgId" } }, "description": "翻页游标对象" } }, "description": "业务数据(结构以实测为准)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": { "hasMore": true, "list": null, "nextKey": { "msgId": 0 } }, "detail": "", "message": "ok", "time": "2026-09-11 20:20:00" } } } } } } }, "/api/message/groupSendPending": { "post": { "tags": [ "消息" ], "summary": "群发助手-发送(待发送消息)", "operationId": "message_groupSendPending", "description": "【2026-09-11】成功态未测(队列为空);id:0 探测返回 -24001155|无法发送一年前的任务。\n\n**安全级别**: write(执行前需二次确认 confirm)", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "id": { "type": "integer", "format": "int64", "description": "[int64] 待发送任务 id(来自 getPendingGroupSendList)" }, "contentList": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "integer", "format": "int64", "description": "消息类型码(0 文本/14 图片/23 视频…)" }, "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "integer", "format": "int64", "description": "类型编码(具体含义随所在对象:成员/部门、图片/视频、节点类型等,详见对应接口)" }, "text": { "type": "string", "description": "type 0/3 的文本内容" } }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" }, "appInfo": { "type": "string", "description": "企微内部透传串(base64);群发/待发送场景需回填,业务方不必解析" } }, "description": "素材内容片段(文案 + 附件)" }, "description": "素材内容片段(文案 + 附件)" }, "conversationType": { "type": "integer", "format": "int64", "description": "[int] 0 客户 / 1 群(以实测为准)" } }, "required": [ "id", "conversationType", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "id": 117159486110430465, "contentList": [ { "contentType": 0, "content": [ { "type": 0, "text": "示例文本" } ], "appInfo": "CAQQiaO51AYY4Y+oq5SAgAMg56GIsQQ=" } ], "conversationType": 0 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/message/getGroupSendRecord": { "post": { "tags": [ "消息" ], "summary": "群发助手-获取群发记录(个人)", "operationId": "message_getGroupSendRecord", "description": "\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" } }, "required": [ "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/contact/getSyncList": { "post": { "tags": [ "联系人" ], "summary": "同步通讯录id", "operationId": "contact_getSyncList", "description": "【2026-09-06 实测】响应 = data.{change, needFullUpdate, svrVersion, nodeList[]};示例裁剪至 2 项。 | 返回通讯录节点列表(type/vid/partyId/seq),再用 fetchUsersProfileBatch 取详情。\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "svrVersion": { "type": "string", "description": "[string] 增量版本号,首次传空" } }, "required": [ "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "svrVersion": "" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "properties": { "change": { "type": "boolean", "description": "相较上次是否有变化" }, "needFullUpdate": { "type": "boolean", "description": "是否需要全量更新(通常首次为 `true`)" }, "svrVersion": { "type": "string", "description": "增量版本号;首次传空串=全量,之后回传上次返回值=增量" }, "nodeList": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "integer", "format": "int64", "description": "类型编码(具体含义随所在对象:成员/部门、图片/视频、节点类型等,详见对应接口)" }, "partyId": { "type": "integer", "format": "int64", "description": "部门/组织 id(int64)" }, "seq": { "type": "integer", "format": "int64", "description": "同步游标(增量翻页位置)" } }, "description": "通讯录节点列表" }, "description": "通讯录节点列表" }, "corpScale": { "type": "integer", "format": "int64", "description": "企业规模标识,含义待确认" } }, "description": "业务数据(结构以实测为准)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": { "change": true, "needFullUpdate": true, "svrVersion": "7681680474451738625_7681681438009196545_3_7223956814780432385_2_7681681438009196545_0", "nodeList": [ { "type": 2, "partyId": 1688856489464990, "seq": 7223519559452459009 }, { "type": 1, "vid": 1688856489464987, "partyId": 1688857448448992, "seq": 7231081125865586689 } ], "corpScale": 1 }, "detail": "", "message": "ok", "time": "2026-09-06 11:12:58" } } } } } } }, "/api/contact/fetchUsersProfileBatch": { "post": { "tags": [ "联系人" ], "summary": "批量获取通讯录详细信息", "operationId": "contact_fetchUsersProfileBatch", "description": "\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "nodeList": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "integer", "format": "int64", "description": "类型编码(具体含义随所在对象:成员/部门、图片/视频、节点类型等,详见对应接口)" }, "partyId": { "type": "integer", "format": "int64", "description": "部门/组织 id(int64)" }, "seq": { "type": "integer", "format": "int64", "description": "同步游标(增量翻页位置)" } }, "description": "通讯录节点列表" }, "description": "通讯录节点列表" } }, "required": [ "nodeList", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "nodeList": [ { "type": 2, "partyId": 1688855319807972, "seq": 7650540819522256897 }, { "type": 1, "vid": 1688855319807969, "partyId": 1688855319807972, "seq": 7650540875642044417 } ] } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/contact/getUserProfileDetail": { "post": { "tags": [ "联系人" ], "summary": "获取用户信息详情", "operationId": "contact_getUserProfileDetail", "description": "\n\n> 【实测差异】data 是数组,每个查询 id 一项 {vid, info, level};不是单对象 data.info。\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "userIdList": { "type": "array", "items": { "type": "integer", "format": "int64", "description": "用户 id 列表(内部成员 vid 或外部联系人 id)" }, "description": "[int64[]] 用户 id 列表(内部成员或外部联系人)" } }, "required": [ "userIdList", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "userIdList": [ 1688855874759204, 1688857990821417, 7881301709020163, 7881300286335405 ] } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "array", "items": { "type": "object" }, "description": "用户资料列表，每项为 `{vid, info, level}`" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/contact/phoneNumberSearch": { "post": { "tags": [ "联系人" ], "summary": "手机号搜索", "operationId": "contact_phoneNumberSearch", "description": "按手机号搜索用户,供添加好友接口使用。\n\n> 响应 `data` 是数组，每项含 `{contactInfo, contactInfoWx, corpInfo, wxTicket, openid, searchStatus, resultType}`；加个人微信取 `openid` + `wxTicket`（作为 `ticket`）；加企业微信取 `contactInfo.uin`（作为 `userid`）+ `contactInfo.corpId`（作为 `corpId`）+ `wxTicket`（作为 `ticket`）。用 `resultType` / `searchStatus` 判断用户类型与是否可添加。\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "phone": { "type": "string", "description": "[string] 手机号" } }, "required": [ "phone", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "phone": "17311125550" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "array", "items": { "type": "object" }, "description": "搜索结果列表，每项含 contactInfo、contactInfoWx、corpInfo、wxTicket、openid、searchStatus、resultType" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/contact/phoneNumberAddWechat": { "post": { "tags": [ "联系人" ], "summary": "通过手机号添加个微", "operationId": "contact_phoneNumberAddWechat", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "ticket": { "type": "string", "description": "加好友票据，取自[手机号搜索](/wecom/contact/phone-number-search)的 `data` 数组对应项的 `wxTicket`，作为 `ticket` 传入" }, "openid": { "type": "string", "description": "对方 openid，取自[手机号搜索](/wecom/contact/phone-number-search)的 `data` 数组对应项的 `openid`" }, "verifyMessage": { "type": "string", "description": "[string] 验证消息" }, "remarkPhone": { "type": "array", "items": { "type": "object", "properties": { "phone": { "type": "string", "description": "电话(外部对象常为空)" } }, "description": "备注手机号列表,每项 `{phone}`" }, "description": "备注手机号列表,每项 `{phone}`" } }, "required": [ "ticket", "openid", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "ticket": "<搜索结果中的票据>", "openid": "<搜索结果中的 openid>", "verifyMessage": "我是某某,添加你方便沟通一下", "remarkPhone": [ { "phone": "" } ] } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/contact/phoneNumberAddWework": { "post": { "tags": [ "联系人" ], "summary": "通过手机号添加企微", "operationId": "contact_phoneNumberAddWework", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "userid": { "type": "integer", "format": "int64", "description": "对方的企微用户 id，取自[手机号搜索](/wecom/contact/phone-number-search)的 `data` 数组对应项的 `contactInfo.uin`" }, "corpId": { "type": "integer", "format": "int64", "description": "对方的企业 id，取自[手机号搜索](/wecom/contact/phone-number-search)的 `data` 数组对应项的 `contactInfo.corpId`" }, "ticket": { "type": "string", "description": "加好友票据，取自[手机号搜索](/wecom/contact/phone-number-search)的 `data` 数组对应项的 `wxTicket`，作为 `ticket` 传入" }, "verifyMessage": { "type": "string", "description": "好友验证语" }, "remarkPhone": { "type": "array", "items": { "type": "object", "properties": { "phone": { "type": "string", "description": "电话(外部对象常为空)" } }, "description": "备注手机号列表,每项 `{phone}`" }, "description": "备注手机号列表,每项 `{phone}`" } }, "required": [ "userid", "corpId", "ticket", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "userid": 312734418777810325, "corpId": 1970324952577074, "ticket": "<搜索结果中的票据>", "verifyMessage": "你好,我是某某,很高兴认识你", "remarkPhone": [ { "phone": "" } ] } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/contact/agreeToNewCustomer": { "post": { "tags": [ "联系人" ], "summary": "同意新客户", "operationId": "contact_agreeToNewCustomer", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "userId": { "type": "integer", "format": "int64", "description": "[int64] 申请添加的客户 id" } }, "required": [ "userId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "userId": 7881300286335405 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/contact/updateExternalContactInfo": { "post": { "tags": [ "联系人" ], "summary": "更新外部联系人信息", "operationId": "contact_updateExternalContactInfo", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "userId": { "type": "integer", "format": "int64", "description": "[int64] 外部联系人 id(文档参数表写作 vid)" }, "remark": { "type": "string", "description": "[string] 描述" }, "realRemark": { "type": "string", "description": "[string] 真实用户备注" }, "remarkPhone": { "type": "array", "items": { "type": "object", "properties": { "phone": { "type": "string", "description": "电话(外部对象常为空)" } }, "description": "备注手机号列表,每项 `{phone}`" }, "description": "备注手机号列表,每项 `{phone}`" }, "companyRemark": { "type": "string", "description": "[string] 企业/公司备注" }, "remarkUrl": { "type": "string", "description": "[string] 描述内的备注 Url" } }, "required": [ "userId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "userId": 7881301709020163, "remark": "测试下", "realRemark": "老大", "remarkPhone": [ { "phone": "15098372134" } ], "companyRemark": "利荣科技", "remarkUrl": "" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/contact/delete": { "post": { "tags": [ "联系人" ], "summary": "删除联系人", "operationId": "contact_delete", "description": "\n\n**安全级别**: destructive(执行前需二次确认 confirm)", "x-safety": "destructive", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "userId": { "type": "integer", "format": "int64", "description": "[int64] 联系人 id" } }, "required": [ "userId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "userId": 7881300286335405 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/contact/setColleagueRemark": { "post": { "tags": [ "联系人" ], "summary": "设置同事备注", "operationId": "contact_setColleagueRemark", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "userId": { "type": "integer", "format": "int64", "description": "[int64] 同事(内部成员)id" }, "remark": { "type": "string", "description": "[string] 备注/描述" }, "description": { "type": "string", "description": "[string] 备注/描述" } }, "required": [ "userId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "userId": 1688855874759204, "remark": "备注", "description": "描述" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/contact/addCard": { "post": { "tags": [ "联系人" ], "summary": "添加名片", "operationId": "contact_addCard", "description": "通过收到的名片添加好友。【2026-09-11 实测】cardSourceUserId 是 uint64 数字非字符串;校验顺序 类型→userId 非零→查资料。\n\n> 【2026-09-11 实测】cardSourceUserId 是 uint64 数字,传字符串被拒。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "userId": { "type": "integer", "format": "int64", "description": "[int64] 名片对应用户 id" }, "ticket": { "type": "string", "description": "[string] 名片消息里的 ticket" }, "verifyMessage": { "type": "string", "description": "[string] 验证消息" }, "cardSourceUserId": { "type": "integer", "format": "int64", "description": "[int64] 名片的发放者 id(uint64 数字,传字符串被拒)" } }, "required": [ "userId", "cardSourceUserId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "userId": 0, "ticket": "", "verifyMessage": "", "cardSourceUserId": 0 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/contact/addRoomMember": { "post": { "tags": [ "联系人" ], "summary": "添加群成员", "operationId": "contact_addRoomMember", "description": "通过群添加群内成员为好友(与 /api/room/addMember 不同:后者是把人拉进群)。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "userId": { "type": "integer", "description": "[int64] 群成员 id", "format": "int64" }, "roomId": { "type": "integer", "description": "[int64] 群 id", "format": "int64" } }, "required": [ "userId", "roomId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "userId": 1688850000000012, "roomId": 10000000000002 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/contact/syncExternal": { "post": { "tags": [ "联系人" ], "summary": "同步外部数据(非企业)", "operationId": "contact_syncExternal", "description": "【2026-09-06 实测】响应 = data.{businessId, list[], hasNext?};每项 {id, itemFlag, seq, createTime, updateTime, content:{userInfo:{uin,name,iconUrl,…}}},无 op 字段,itemFlag 删除态取值待样本;示例裁剪至 1 项并脱敏。 | 同步外部联系人(客户)数据;收到回调 Msg contentType 2131 时应调用。\n\n> 【实测现象】今日 businessId:1 返回 -2003|(疑游标失效/无增量);businessId:0 返回 code 0 但 list 空。itemFlag 删除态取值待样本(每项无 op 字段)。\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "seq": { "type": "integer", "format": "int64", "description": "[int64] 同步游标,首次 0" }, "businessId": { "type": "integer", "format": "int64", "description": "[int] 业务 id,示例 1" } }, "required": [ "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "seq": 15873502, "businessId": 0 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "properties": { "businessId": { "type": "integer", "format": "int64", "description": "0 可用" }, "list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "记录/文件业务标识" }, "itemFlag": { "type": "integer", "format": "int64", "description": "变更标志;实测 `0`,删除态取值待确认(getExternalContact 曾见 `0`/`1`)" }, "seq": { "type": "integer", "format": "int64", "description": "同步游标(增量翻页位置)" }, "createTime": { "type": "integer", "format": "int64", "description": "建立 / 更新时间戳(秒)" }, "updateTime": { "type": "integer", "format": "int64", "description": "建立 / 更新时间戳(秒)" }, "content": { "type": "object", "properties": { "userInfo": { "type": "object", "properties": { "uin": { "type": "integer", "format": "int64", "description": "用户唯一 id(int64,注意精度)" }, "name": { "type": "string", "description": "昵称 / 显示名" }, "emailAddr": { "type": "string", "description": "个人邮箱" }, "birthday": { "type": "string", "description": "生日 `YYYY-MM-DD HH:MM:SS`" }, "phone": { "type": "string", "description": "电话(外部对象常为空)" }, "number": { "type": "string", "description": "工号" }, "gender": { "type": "integer", "format": "int64", "description": "性别(1 男 / 2 女)" }, "iconUrl": { "type": "string", "description": "头像 url" }, "corpId": { "type": "integer", "format": "int64", "description": "所属企业唯一 id(int64)" }, "attr": { "type": "integer", "format": "int64", "description": "属性位掩码(bitmask),各 bit 含义待确认" }, "dispOrder": { "type": "integer", "format": "int64", "description": "通讯录 / 部门内显示排序" }, "bizUin": { "type": "integer", "format": "int64", "description": "企业 uin,含义待确认" }, "alias": { "type": "string", "description": "别名 / 花名" }, "mainPartyId": { "type": "integer", "format": "int64", "description": "主部门 id" }, "gid": { "type": "integer", "format": "int64", "description": "全局 id(跨企业标识),含义待确认" }, "isNameVerified": { "type": "boolean", "description": "是否已实名认证" }, "createSource": { "type": "integer", "format": "int64", "description": "创建来源(外部客户常见)" }, "internationCode": { "type": "string", "description": "国际区号,如 `86`" }, "bindEmailStatus": { "type": "integer", "format": "int64", "description": "邮箱绑定状态(观测到 `2`=已绑定 / `1`),枚举待确认" }, "englishName": { "type": "string", "description": "英文名" }, "customInfo": { "type": "object", "properties": {}, "description": "自定义字段集合(常为空对象)" }, "nameVerifyStatus": { "type": "integer", "format": "int64", "description": "实名认证状态(观测 `1`)" }, "realName": { "type": "string", "description": "实名(示例已脱敏)" }, "vCorpUseStatus": { "type": "integer", "format": "int64", "description": "企业使用状态(观测 `1000`),含义待确认" }, "inviteVid": { "type": "integer", "format": "int64", "description": "邀请人 vid" }, "holidayInfo": { "type": "object", "properties": { "holidayStatus": { "type": "integer", "format": "int64", "description": "假期状态 / 新版假期状态" }, "holidayDesc": { "type": "string", "description": "假期描述文案" }, "oldHolidayIconIndex": { "type": "integer", "format": "int64", "description": "假期头像挂件索引 / 旧索引" }, "createTime": { "type": "integer", "format": "int64", "description": "建立 / 更新时间戳(秒)" }, "holidayInfoId": { "type": "integer", "format": "int64", "description": "假期信息 id" }, "holidayIconIndex": { "type": "integer", "format": "int64", "description": "假期头像挂件索引 / 旧索引" }, "holidayGenerateSrc": { "type": "integer", "format": "int64", "description": "假期来源(含义待确认)" }, "holidayStatusNew": { "type": "integer", "format": "int64", "description": "假期状态 / 新版假期状态" } }, "description": "休假信息(`holidayStatus`/`holidayDesc`/... )" }, "xcxStyle": { "type": "integer", "format": "int64", "description": "小程序名片样式,含义待确认" }, "attr2": { "type": "integer", "format": "int64", "description": "属性位掩码(bitmask),各 bit 含义待确认" }, "tencentInfo": { "type": "object", "properties": {}, "description": "腾讯生态相关(常为空对象)" }, "isSyncInnerPosition": { "type": "boolean", "description": "是否同步内部职位" }, "unionId": { "type": "string", "description": "微信 unionId(跨应用用户标识)" }, "vCode": { "type": "string", "description": "名片/验证码(形如 `vc31f1...`)" }, "schoolUserType": { "type": "integer", "format": "int64", "description": "学校 / 高校身份类型,含义待确认" }, "personalWorkType": { "type": "integer", "format": "int64", "description": "个人工作类型,含义待确认" }, "attr3": { "type": "integer", "format": "int64", "description": "属性位掩码(bitmask),各 bit 含义待确认" } }, "description": "客户用户信息(字段见字典)" }, "corpInfo": { "type": "object", "properties": { "corpId": { "type": "integer", "format": "int64", "description": "所属企业唯一 id(int64)" }, "vid": { "type": "integer", "format": "int64", "description": "联系人 id(int64)" }, "corpName": { "type": "string", "description": "所属企业名称" }, "createTime": { "type": "integer", "format": "int64", "description": "建立 / 更新时间戳(秒)" }, "staffNum": { "type": "integer", "format": "int64" }, "trust": { "type": "boolean" }, "corpLogo": { "type": "string" }, "corpDesc": { "type": "string", "description": "【2026-09-11 实测新增】 企业描述(仅 `getUserProfileDetail` 的部分 info 出现)。" }, "adminVid": { "type": "integer", "format": "int64" }, "isAccepted": { "type": "boolean" }, "corpStat": { "type": "integer", "format": "int64" }, "corpFullName": { "type": "string" }, "cmSubmitTime": { "type": "integer", "format": "int64" }, "createSourceInfo": { "type": "string" }, "verifyMsg": { "type": "string" }, "hasInfoCorp": { "type": "boolean" }, "virtualCreateDomainName": { "type": "string" }, "language": { "type": "integer", "format": "int64" }, "corpCardUrl": { "type": "string" }, "authedDomain": { "type": "string" }, "vSuperadminVid": { "type": "integer", "format": "int64" }, "bAuthedLicence": { "type": "boolean" }, "joinNeedVerify": { "type": "boolean" }, "pstnOfficePhoneState": { "type": "integer", "format": "int64" }, "authLicenceStatus": { "type": "integer", "format": "int64" }, "sCorpId": { "type": "string" }, "corpAppWxaInfo": { "type": "object", "properties": { "userName": { "type": "string" }, "appId": { "type": "string", "description": "小程序 appId" }, "enterPath": { "type": "string" }, "versionType": { "type": "integer", "format": "int64" }, "version": { "type": "integer", "format": "int64", "description": "版本号,无特殊需求传 `0`" } } }, "isOverseasCorp": { "type": "boolean" } }, "description": "企业信息(未搜到企业时 `corpId=0`)" }, "flag": { "type": "integer", "format": "int64", "description": "消息标志位 / 设备信息 / 摘要;观测到 `flag` 取 0 或 16777216,`summary` 常为空。精确含义待确认" }, "applyReason": { "type": "string", "description": "添加时的申请语" }, "extraInfo": { "type": "object", "properties": { "remarks": { "type": "string", "description": "备注描述" }, "wxTicket": { "type": "string", "description": "加好友票据;传给 add 接口的 `ticket`(实测长约 160 字符)" }, "realRemark": { "type": "string", "description": "真实用户备注(改对方在你处的显示名)" }, "remarkUrl": { "type": "string", "description": "描述内的备注 URL" }, "addCustomerTime": { "type": "integer", "format": "int64", "description": "添加为客户的时间戳" }, "companyRemark": { "type": "string", "description": "企业/公司备注" }, "labelId": { "type": "array", "items": { "type": "object", "properties": { "labelId": { "type": "integer", "format": "int64", "description": "打在该客户上的标签,每项 `{labelId, groupId, corpOrVid, businessType, serviceGroupId}`" }, "corpOrVid": { "type": "integer", "format": "int64" }, "groupId": { "type": "integer", "format": "int64", "description": "分组 id(0=无)" }, "businessType": { "type": "integer", "format": "int64", "description": "业务类型 / 排序 / 服务组 id(原样回传)" }, "serviceGroupId": { "type": "integer", "format": "int64", "description": "业务类型 / 排序 / 服务组 id(原样回传)" } }, "description": "打在该客户上的标签,每项 `{labelId, groupId, corpOrVid, businessType, serviceGroupId}`" }, "description": "打在该客户上的标签,每项 `{labelId, groupId, corpOrVid, businessType, serviceGroupId}`" }, "isFirstChat": { "type": "boolean", "description": "是否首次会话" }, "remarkTime": { "type": "integer", "format": "int64", "description": "备注时间戳" } }, "description": "统计明细:`senderNums`(已发)/`senderTotalNums`(应发)/`serviceMember`" }, "sourceInfo": { "type": "object", "properties": { "sourceType": { "type": "integer", "format": "int64", "description": "来源类型" }, "applyMode": { "type": "integer", "format": "int64", "description": "申请方式" } } } }, "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" }, "createSeq": { "type": "integer", "format": "int64", "description": "创建游标" }, "dataType": { "type": "integer", "format": "int64", "description": "数据类型,含义待确认(实测 `0`)" } }, "description": "消息对象数组" }, "description": "消息对象数组" } }, "description": "业务数据(结构以实测为准)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": { "businessId": 0, "list": [ { "id": 1688855655434798, "itemFlag": 0, "seq": 9425784, "createTime": 1697595471, "updateTime": 1699432125, "content": { "userInfo": { "uin": 1688855655434798, "name": "蜘蛛侠", "emailAddr": "", "birthday": "1970-01-01 00:00:00", "phone": "", "number": "", "gender": 1, "iconUrl": "https://wx.qlogo.cn/mmhead/bSb5dSzPn0KzE4xrkiadlR6Q7HibrUOeaET22ibE8Q7pqGdmtHs0nWGhg/0", "corpId": 1970325925998027, "attr": 137757248, "dispOrder": 0, "bizUin": 0, "alias": "", "mainPartyId": 1688855655434807, "gid": 2251802468974430, "isNameVerified": true, "createSource": 1, "internationCode": "86", "bindEmailStatus": 2, "englishName": "ZhiZhuXia", "customInfo": {}, "nameVerifyStatus": 1, "realName": "张**", "vCorpUseStatus": 1000, "inviteVid": 0, "holidayInfo": { "holidayStatus": 0, "holidayDesc": "", "oldHolidayIconIndex": 0, "createTime": 0, "holidayInfoId": 0, "holidayIconIndex": 0, "holidayGenerateSrc": 0, "holidayStatusNew": 0 }, "xcxStyle": 0, "attr2": 536871168, "tencentInfo": {}, "isSyncInnerPosition": true, "unionId": "ozynqshxD5vlYYP1MZQ_ZFmugT3M", "vCode": "vc14653af37ba5080e", "schoolUserType": 3, "personalWorkType": 0, "attr3": 0 }, "corpInfo": { "corpId": 1970325925998027, "vid": 1688855655434798, "corpName": "奥特曼打葫芦娃", "createTime": 1685974036, "staffNum": 0, "trust": true, "corpLogo": "https://wework.qpic.cn/wwpic/186583_HKZLN-kIRie5_Ux_1685974037/0", "corpDesc": "", "adminVid": 1688855655434798, "isAccepted": true, "corpStat": 0, "corpFullName": "", "cmSubmitTime": 0, "createSourceInfo": "", "verifyMsg": "", "hasInfoCorp": false, "virtualCreateDomainName": "", "language": 1, "corpCardUrl": "https://work.weixin.qq.com/wework_admin/user/h5/corp?", "authedDomain": "", "vSuperadminVid": 1688855655434798, "bAuthedLicence": false, "joinNeedVerify": false, "pstnOfficePhoneState": 0, "authLicenceStatus": 1, "sCorpId": "<企业 corpId>", "corpAppWxaInfo": { "userName": "gh_303bdfa3334c@app", "appId": "<小程序 appId>", "enterPath": "/pages/index/index.html", "versionType": 0, "version": 0 }, "isOverseasCorp": false }, "flag": 2057, "applyReason": "", "extraInfo": { "remarks": "", "wxTicket": "", "realRemark": "", "remarkUrl": "", "addCustomerTime": 1697595472, "companyRemark": "", "labelId": [ { "labelId": 14073752485732091, "corpOrVid": 1970325156983916, "groupId": 14073752485732090, "businessType": 0, "serviceGroupId": 0 }, { "labelId": 14073752485732092, "corpOrVid": 1970325156983916, "groupId": 14073752485732090, "businessType": 0, "serviceGroupId": 0 } ], "isFirstChat": true, "remarkTime": 1697614272 }, "sourceInfo": { "sourceType": 1, "applyMode": 2 } }, "createSeq": 9325776, "dataType": 0 } ] }, "detail": "", "message": "ok", "time": "2026-09-06 11:26:14" } } } } } } }, "/api/contact/updateLabel": { "post": { "tags": [ "联系人" ], "summary": "更新用户标签", "operationId": "contact_updateLabel", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "userId": { "type": "integer", "format": "int64", "description": "[int64] 被打标签的用户 id" }, "operItems": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "integer", "format": "int64", "description": "操作:`1` 新增 / `2` 删除 / `3` 修改" }, "label": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "标签 id" }, "name": { "type": "string", "description": "标签名" }, "dataType": { "type": "integer", "format": "int64", "description": "数据类型：`1` 标签、`2` 标签组" }, "bDeleted": { "type": "integer", "format": "int64", "description": "是否已删除(0/1)" }, "labelGroupId": { "type": "integer", "format": "int64", "description": "所属标签组 id" }, "createTime": { "type": "integer", "format": "int64", "description": "建立 / 更新时间戳(秒)" }, "labelType": { "type": "integer", "format": "int64", "description": "标签类型：`1` 企业标签、`2` 个人标签" }, "businessType": { "type": "integer", "format": "int64", "description": "业务类型 / 排序 / 服务组 id(原样回传)" }, "order": { "type": "integer", "format": "int64", "description": "业务类型 / 排序 / 服务组 id(原样回传)" }, "serviceGroupId": { "type": "integer", "format": "int64", "description": "业务类型 / 排序 / 服务组 id(原样回传)" } }, "description": "完整标签对象(须原样取自 `/api/label/sync`)" } }, "description": "标签操作项列表" }, "description": "标签操作项列表" } }, "required": [ "userId", "operItems", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "userId": 1688857990821417, "operItems": [ { "op": 3, "label": { "id": 14073750445976458, "name": "测试", "dataType": 1, "bDeleted": 0, "labelGroupId": 14073751857989781, "createTime": 1787872137, "labelType": 2, "businessType": 0, "order": 0, "serviceGroupId": 0 } } ] } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/room/getInfo": { "post": { "tags": [ "群" ], "summary": "获取群资料", "operationId": "room_getInfo", "description": "文档 url 末尾带空格,实现时去掉。\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "roomId": { "type": "integer", "format": "int64", "description": "[int64] 群 id" } }, "required": [ "roomId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "roomId": 10786447466811918 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/room/delMember": { "post": { "tags": [ "群" ], "summary": "移除群成员", "operationId": "room_delMember", "description": "\n\n**安全级别**: destructive(执行前需二次确认 confirm)", "x-safety": "destructive", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "roomId": { "type": "integer", "format": "int64", "description": "群会话 id(int64);非群消息为 0" }, "userIdList": { "type": "array", "items": { "type": "integer", "format": "int64", "description": "用户 id 列表(内部成员 vid 或外部联系人 id)" }, "description": "[int64[]] 要移除的成员 id" } }, "required": [ "userIdList", "roomId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "roomId": 1970325823022815, "userIdList": [ 1688855319807969 ] } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/room/addMember": { "post": { "tags": [ "群" ], "summary": "添加群成员", "operationId": "room_addMember", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "roomId": { "type": "integer", "format": "int64", "description": "群会话 id(int64);非群消息为 0" }, "userIdList": { "type": "array", "items": { "type": "integer", "format": "int64", "description": "用户 id 列表(内部成员 vid 或外部联系人 id)" }, "description": "[int64[]] 要邀请入群的用户 id" } }, "required": [ "userIdList", "roomId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "roomId": 10786447466811918, "userIdList": [ 1688855319807969 ] } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/room/setName": { "post": { "tags": [ "群" ], "summary": "设置群名", "operationId": "room_setName", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "roomId": { "type": "integer", "format": "int64", "description": "群会话 id(int64);非群消息为 0" }, "roomName": { "type": "string", "description": "[string] 新群名" } }, "required": [ "roomName", "roomId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "roomId": 10786447466811918, "roomName": "橘子炸鸡代理1" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/room/getQrCode": { "post": { "tags": [ "群" ], "summary": "获取群二维码", "operationId": "room_getQrCode", "description": "群主/管理员开启进群验证时二维码被停用,返回错误码 -18000059。文档 url 末尾带空格。\n\n> 【实测差异】响应字段为 data.roomQrcode(群二维码 PNG 的 base64,非 url)/ data.imgUrl(群头像 url)/ data.roomId;旧文档写的 qrcodeImage/qrcodeUrl 已不适用。渲染二维码用 data:image/png;base64,。\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "roomId": { "type": "integer", "format": "int64", "description": "群会话 id(int64);非群消息为 0" } }, "required": [ "roomId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "roomId": 1970325823022815 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/room/setNotice": { "post": { "tags": [ "群" ], "summary": "修改群公告", "operationId": "room_setNotice", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "roomId": { "type": "integer", "format": "int64", "description": "群会话 id(int64);非群消息为 0" }, "notice": { "type": "string", "description": "[string] 公告内容" } }, "required": [ "notice", "roomId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "roomId": 1970326472001502, "notice": "测试公告" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/room/setAdmin": { "post": { "tags": [ "群" ], "summary": "设置管理员", "operationId": "room_setAdmin", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "roomId": { "type": "integer", "format": "int64", "description": "群会话 id(int64);非群消息为 0" }, "userId": { "type": "integer", "format": "int64", "description": "[int64] 成员 id" }, "enable": { "type": "boolean", "description": "[bool] true 设为管理员 / false 取消" } }, "required": [ "userId", "enable", "roomId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "roomId": 1970325823022815, "userId": 1688855319807969, "enable": false } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/room/changeOwner": { "post": { "tags": [ "群" ], "summary": "转让群主", "operationId": "room_changeOwner", "description": "\n\n**安全级别**: destructive(执行前需二次确认 confirm)", "x-safety": "destructive", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "roomId": { "type": "integer", "format": "int64", "description": "群会话 id(int64);非群消息为 0" }, "userId": { "type": "integer", "format": "int64", "description": "[int64] 新群主 id" } }, "required": [ "userId", "roomId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "roomId": 1970325823022815, "userId": 1688855319807969 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/room/create": { "post": { "tags": [ "群" ], "summary": "创建客户群", "operationId": "room_create", "description": "【2026-09-11 实测】body 只需 appid 即建**空**客户群;返回 {url(邀请链接), title, content, imgUrl(默认群头像), roomId}。旧 schema 的 avatarUrl/desc/extra/inviteUrl 字段名已不适用。建群后用 addMember 拉人。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" } }, "required": [ "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "properties": { "url": { "type": "string", "description": "链接 / 资源地址" }, "title": { "type": "string", "description": "标题" }, "content": { "type": "string", "description": "消息内容;文本为数组、媒体为对象;未解析的消息为 `{msgType, hex}`(hex=protobuf 原始十六进制)" }, "imgUrl": { "type": "string", "description": "群头像 url(与列表项 `roomUrl` 同源)" }, "roomId": { "type": "integer", "format": "int64", "description": "群会话 id(int64);非群消息为 0" } }, "description": "业务数据(结构以实测为准)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": { "url": "https://work.weixin.qq.com/wework_admin/room/join/wx?invite_source=146&vcode=…", "title": "邀请你加入企业微信群聊", "content": "张**在企业微信中邀请你加入群聊,用正式的名片聊工作", "imgUrl": "http://rescdn.qqmail.com/node/ww/wwmng/…/DefaultGroupAvatar.png", "roomId": 10745787645721636 }, "detail": "", "message": "ok", "time": "2026-09-11 20:00:00" } } } } } } }, "/api/room/setMyNickname": { "post": { "tags": [ "群" ], "summary": "变更本群名称", "operationId": "room_setMyNickname", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "roomId": { "type": "integer", "format": "int64", "description": "群会话 id(int64);非群消息为 0" }, "nickname": { "type": "string", "description": "[string] 我在本群的昵称" } }, "required": [ "nickname", "roomId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "roomId": 10910663383050506, "nickname": "虾·" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/room/saveToContact": { "post": { "tags": [ "群" ], "summary": "保存通讯录(仅限群)", "operationId": "room_saveToContact", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "roomId": { "type": "integer", "format": "int64", "description": "群会话 id(int64);非群消息为 0" }, "enable": { "type": "boolean", "description": "[bool] true 保存到通讯录 / false 取消保存" } }, "required": [ "enable", "roomId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "roomId": 1970325823022815, "enable": false } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/room/getMyCustomerGroupList": { "post": { "tags": [ "群" ], "summary": "获取我的客户群列表", "operationId": "room_getMyCustomerGroupList", "description": "\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "limit": { "type": "integer", "format": "int64", "description": "[int] 最多返回条数" } }, "required": [ "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "limit": 2000 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/room/top": { "post": { "tags": [ "群" ], "summary": "设置房间置顶/取消", "operationId": "room_top", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "roomId": { "type": "integer", "format": "int64", "description": "[int64] 会话 id(群或联系人)" }, "enable": { "type": "boolean", "description": "[bool] true 置顶 / false 取消" } }, "required": [ "roomId", "enable", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "roomId": 7881301709020163, "enable": false } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/room/quit": { "post": { "tags": [ "群" ], "summary": "退出群聊", "operationId": "room_quit", "description": "\n\n**安全级别**: destructive(执行前需二次确认 confirm)", "x-safety": "destructive", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "roomId": { "type": "integer", "description": "[int64] 群 id", "format": "int64" } }, "required": [ "roomId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "roomId": 10000000000002 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/room/inviteConfirm": { "post": { "tags": [ "群" ], "summary": "设置房间邀请确认(群管理)", "operationId": "room_inviteConfirm", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "roomId": { "type": "integer", "format": "int64", "description": "群会话 id(int64);非群消息为 0" }, "enable": { "type": "boolean", "description": "[bool] true 开启入群邀请需群主确认" } }, "required": [ "enable", "roomId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "roomId": 10786447466811918, "enable": true } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/room/forbidRename": { "post": { "tags": [ "群" ], "summary": "禁止改群名(群管理)", "operationId": "room_forbidRename", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "roomId": { "type": "integer", "format": "int64", "description": "群会话 id(int64);非群消息为 0" }, "enable": { "type": "boolean", "description": "[bool] true 禁止成员改群名" } }, "required": [ "enable", "roomId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "roomId": 10786447466811918, "enable": false } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/room/forbidMutualAdd": { "post": { "tags": [ "群" ], "summary": "禁止添加群成员(群管理)", "operationId": "room_forbidMutualAdd", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "roomId": { "type": "integer", "format": "int64", "description": "群会话 id(int64);非群消息为 0" }, "enable": { "type": "boolean", "description": "[bool] true 禁止成员互相添加/拉人" } }, "required": [ "enable", "roomId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "roomId": 10786447466811918, "enable": true } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/room/disband": { "post": { "tags": [ "群" ], "summary": "解散群聊(群主)", "operationId": "room_disband", "description": "> 【注意】服务端标记该接口为开发中，响应结构可能变动。\n\n**安全级别**: destructive(执行前需二次确认 confirm)", "x-safety": "destructive", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "roomid": { "type": "integer", "format": "int64", "description": "[int64] 群 id(注意文档字段名小写 roomid)" } }, "required": [ "roomid", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "roomid": 0 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/room/setRemark": { "post": { "tags": [ "群" ], "summary": "设置群备注", "operationId": "room_setRemark", "description": "> 【注意】服务端标记该接口为开发中，响应结构可能变动。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "roomId": { "type": "integer", "format": "int64", "description": "群会话 id(int64);非群消息为 0" }, "remark": { "type": "string", "description": "[string] 群备注" } }, "required": [ "remark", "roomId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "roomId": 0, "remark": "" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/friend/sendSns": { "post": { "tags": [ "客户朋友圈" ], "summary": "发布朋友圈", "operationId": "friend_sendSns", "description": "\n\n**安全级别**: write(执行前需二次确认 confirm)", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "xid": { "type": "array", "items": {}, "description": "[array] 可见范围用户 id 列表" }, "content": { "type": "string", "description": "[string] 文字内容" }, "mediaList": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "integer", "format": "int64", "description": "类型编码(具体含义随所在对象:成员/部门、图片/视频、节点类型等,详见对应接口)" }, "fileId": { "type": "string", "description": "CDN 文件业务标识(即 id)" }, "videoLen": { "type": "integer", "format": "int64", "description": "视频时长(秒),仅 type=2" }, "md5": { "type": "string", "description": "文件内容 MD5,收发方一致性校验" }, "size": { "type": "integer", "format": "int64", "description": "文件字节数" }, "storeType": { "type": "integer", "format": "int64", "description": "存储类型,通常 0" } }, "description": "媒体列表(见下)。无媒体时字段缺省" }, "description": "媒体列表(见下)。无媒体时字段缺省" }, "poiInfo": { "type": "object", "properties": { "city": { "type": "string" }, "latitude": { "type": "string", "description": "纬度" }, "longitude": { "type": "string", "description": "经度" }, "poiAddress": { "type": "string" }, "poiClassifyId": { "type": "string" }, "poiClassifyType": { "type": "string" } }, "description": "[object] 位置" }, "linkInfo": { "type": "object", "properties": {}, "description": "[object] 链接" }, "visibleType": { "type": "boolean", "description": "[bool] 可见类型" }, "isGroupSend": { "type": "boolean", "description": "[bool] 是否群发" } }, "required": [ "content", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "xid": [], "content": "测下100", "mediaList": [ { "type": 2, "fileId": "*1*<大文件 id>", "videoLen": 1, "md5": "f93dc595ca1a990d94aa8330ff31c318", "size": 369520, "storeType": 0 }, { "type": 3, "fileId": "*1*<大文件 id>", "md5": "7cb5c01f3809f277fc522cad774fadae", "size": 10782, "storeType": 0 } ], "poiInfo": { "city": "汕尾市", "latitude": "-180", "longitude": "-180", "poiAddress": "", "poiClassifyId": "", "poiClassifyType": "" }, "linkInfo": {}, "visibleType": false, "isGroupSend": false } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/friend/getSnsList": { "post": { "tags": [ "客户朋友圈" ], "summary": "获取朋友圈列表", "operationId": "friend_getSnsList", "description": "\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "seq": { "type": "integer", "format": "int64", "description": "[int64] 翻页游标,首次 0" }, "limit": { "type": "integer", "format": "int64", "description": "[int] 条数" } }, "required": [ "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "seq": 0, "limit": 30 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/friend/setSnsSignature": { "post": { "tags": [ "客户朋友圈" ], "summary": "设置朋友圈签名", "operationId": "friend_setSnsSignature", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "sign": { "type": "string", "description": "[string] 签名" } }, "required": [ "sign", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "sign": "测试下00000000" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/friend/likeSns": { "post": { "tags": [ "客户朋友圈" ], "summary": "朋友圈点赞", "operationId": "friend_likeSns", "description": "\n\n> 【2026-09-11 实测定论】`cancel=true` = 点赞,`cancel=false` = 取消点赞(与字面相反)。可自证:getSnsDetails/getSnsList 的 likeList 随点赞状态增删。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "sid": { "type": "integer", "format": "int64", "description": "[int64] 朋友圈 id" }, "cancel": { "type": "boolean", "description": "[bool] true = 点赞，false = 取消点赞（与字段名字面相反，2026-09-11 实测定论）" } }, "required": [ "sid", "cancel", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "sid": 7664681089236779530, "cancel": false } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/friend/getSnsDetails": { "post": { "tags": [ "客户朋友圈" ], "summary": "获取朋友圈的详情", "operationId": "friend_getSnsDetails", "description": "\n\n> 【实测差异】现返回 likeList/commentList(另有 deleteCommentList);commentList[].comment 是 base64(需解码),content 是明文。\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "sid": { "type": "integer", "format": "int64", "description": "[int64] 朋友圈 id" } }, "required": [ "sid", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "sid": 7679434645476480196 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/friend/commentSns": { "post": { "tags": [ "客户朋友圈" ], "summary": "发布朋友圈评论", "operationId": "friend_commentSns", "description": "\n\n> 【坑】refCommentId(追评)被上游静默丢弃;响应 commentId 恒为 0,删评前需先查列表读回真实 id。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "sid": { "type": "integer", "format": "int64", "description": "[int64] 朋友圈内容 id" }, "content": { "type": "string", "description": "[string] 评论内容" }, "refCommentId": { "type": "integer", "format": "int64", "description": "[int64] 追评时填被回复评论的 commentId,非追评填 0" } }, "required": [ "sid", "content", "refCommentId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "sid": 7658992575255311044, "content": "评论内容122333", "refCommentId": 3 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/friend/deleteSnsComment": { "post": { "tags": [ "客户朋友圈" ], "summary": "删除朋友圈评论", "operationId": "friend_deleteSnsComment", "description": "\n\n**安全级别**: destructive(执行前需二次确认 confirm)", "x-safety": "destructive", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "sid": { "type": "integer", "format": "int64", "description": "[int64] 朋友圈 id" }, "commentId": { "type": "integer", "format": "int64", "description": "[int64] 评论 id" } }, "required": [ "sid", "commentId", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "sid": 0, "commentId": 3 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/friend/deleteSns": { "post": { "tags": [ "客户朋友圈" ], "summary": "删除朋友圈", "operationId": "friend_deleteSns", "description": "\n\n**安全级别**: destructive(执行前需二次确认 confirm)", "x-safety": "destructive", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "sid": { "type": "integer", "format": "int64", "description": "[int64] 朋友圈 id" } }, "required": [ "sid", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "sid": 7663992953016366174 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/cdn/uploadImage": { "post": { "tags": [ "CDN 文件" ], "summary": "上传CDN图片", "operationId": "cdn_uploadImage", "description": "【2026-09-06 实测】data 字段名即 sendImage content 所需(id/size/md5/aesKey/thumb* …);旧文档写的 fileId/fileKey/fileMd5/fileSize/thumbSize 字段名已不存在。返回值直接用于 sendImage / sendMiniProgram 封面。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "fileName": { "type": "string", "description": "[string] 文件名" }, "base64": { "type": "string", "description": "[string] 图片 base64(不含 data: 前缀)" } }, "required": [ "fileName", "base64", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "fileName": "示例图片.jpeg", "base64": "<图片 base64>" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "记录/文件业务标识" }, "size": { "type": "integer", "format": "int64", "description": "文件字节数" }, "width": { "type": "integer", "format": "int64", "description": "宽(像素)" }, "height": { "type": "integer", "format": "int64", "description": "高(像素)" }, "aesKey": { "type": "string", "description": "AES 下载解密密钥;CDN 存的是加密字节,下载后用它解密" }, "md5": { "type": "string", "description": "文件内容 MD5,收发方一致性校验" }, "midImageFileSize": { "type": "integer", "format": "int64", "description": "中图字节数" }, "thumbFileSize": { "type": "integer", "format": "int64", "description": "缩略图字节数" }, "thumbWidth": { "type": "integer", "format": "int64", "description": "缩略图宽" }, "thumbHeight": { "type": "integer", "format": "int64", "description": "缩略图高" }, "thumbMd5": { "type": "string", "description": "缩略图 MD5" } }, "description": "业务数据(结构以实测为准)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": { "id": "3068…0400", "size": 3788, "width": 200, "height": 120, "aesKey": "a80e52a7191df0a1c2aac34076898df4", "md5": "2228e4e55326a9e5c5478b40a22499d0", "midImageFileSize": 3562, "thumbFileSize": 3562, "thumbWidth": 200, "thumbHeight": 120, "thumbMd5": "9736a9f86ba94311a28e1b4ed7115a5a" }, "detail": "", "message": "ok", "time": "2026-09-06 11:40:54" } } } } } } }, "/api/cdn/uploadVideo": { "post": { "tags": [ "CDN 文件" ], "summary": "上传CDN视频", "operationId": "cdn_uploadVideo", "description": "【2026-09-11 实测】返回新字段名 id/aesKey/md5/size + duration/width/height/thumbUrl(封面为单个 thumbUrl 直链,无 thumbMd5/thumbSize/thumb宽高 分列);size/duration/宽高 与源视频一致。一次上传同时落地视频(download fileType=4)与封面(fileType=3)两变体,md5 各自一致。小视频 base64 直传;大视频走 uploadBigFile。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "base64": { "type": "string", "description": "[string] 视频 base64" }, "fileName": { "type": "string", "description": "[string] 文件名" }, "thumbBase64": { "type": "string", "description": "[string] 封面图 base64" } }, "required": [ "base64", "thumbBase64", "fileName", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "base64": "<视频 base64>", "fileName": "123123.MP4", "thumbBase64": "<封面 jpg base64>" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "记录/文件业务标识" }, "size": { "type": "integer", "format": "int64", "description": "文件字节数" }, "duration": { "type": "integer", "format": "int64", "description": "时长(秒)" }, "width": { "type": "integer", "format": "int64", "description": "宽(像素)" }, "height": { "type": "integer", "format": "int64", "description": "高(像素)" }, "thumbUrl": { "type": "string", "description": "封面图 url" }, "aesKey": { "type": "string", "description": "AES 下载解密密钥;CDN 存的是加密字节,下载后用它解密" }, "md5": { "type": "string", "description": "文件内容 MD5,收发方一致性校验" } }, "description": "业务数据(结构以实测为准)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": { "id": "3068…0400", "size": 2044, "duration": 1, "width": 320, "height": 240, "thumbUrl": "https://wework.qpic.cn/wwpic3az/…/0", "aesKey": "127388d4…", "md5": "38cbde78…" }, "detail": "", "message": "ok", "time": "2026-09-11 20:10:00" } } } } } } }, "/api/cdn/uploadFile": { "post": { "tags": [ "CDN 文件" ], "summary": "上传CDN文件", "operationId": "cdn_uploadFile", "description": "用于 sendFile / sendVoice。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "fileName": { "type": "string", "description": "[string] 文件名(语音需 .silk)" }, "base64": { "type": "string", "description": "[string] 文件 base64" } }, "required": [ "fileName", "base64", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "fileName": "wework_voice_5s.silk", "base64": "<文件 base64>" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "properties": { "fileId": { "type": "string", "description": "CDN 文件业务标识(即 id)" }, "aesKey": { "type": "string", "description": "AES 下载解密密钥;CDN 存的是加密字节,下载后用它解密" }, "fileKey": { "type": "string", "description": "CDN 文件会话 key(上传返回)" }, "fileName": { "type": "string", "description": "文件名(带扩展名)" }, "fileMd5": { "type": "string", "description": "文件 MD5" }, "fileSize": { "type": "integer", "format": "int64", "description": "文件字节数" } }, "description": "业务数据(结构以实测为准)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": { "fileId": "3067...0400", "aesKey": "cd38a587cbf5305338883db51810fd2b", "fileKey": "78d237d1-1efb-4a38-9976-8a26f8757a7c", "fileName": "wework_voice_5s.silk", "fileMd5": "0cc175b9c0f1b6a831c399e269772661", "fileSize": 1 }, "detail": "", "message": "ok", "time": "2026-06-22 02:20:25" } } } } } } }, "/api/cdn/download": { "post": { "tags": [ "CDN 文件" ], "summary": "CDN下载", "operationId": "cdn_download", "description": "下载收到的消息附件(图片/视频/文件)。\n\n> 【坑】fileType:1 原图 / 2 压缩图;uploadImage 落地的是压缩图,回环下载需 fileType=2。上传返回的 id+aesKey 即下载凭证(回环 md5 一致)。\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "fileId": { "type": "string", "description": "[string] 文件 id" }, "fileType": { "type": "integer", "format": "int64", "description": "[int] 1 原图 / 2 压缩图 / 3 封面图 / 4 视频 / 5 文件" }, "aesKey": { "type": "string", "description": "[string] 文件 AESKey" } }, "required": [ "fileId", "fileType", "aesKey", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "fileId": "305f...0000", "fileType": 2, "aesKey": "8a8bbce1887ce81517b7fedac2bdfb17" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/cdn/uploadBigFile": { "post": { "tags": [ "CDN 文件" ], "summary": "上传CDN大文件", "operationId": "cdn_uploadBigFile", "description": "异步:请求后立即返回 fileMd5 和 fileSize;上传完成后发出大文件上传完成推送(上传失败时推送结构相同),推送里的 md5、requestId 与本接口返回一致,可作校验依据。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "fileUrl": { "type": "string", "description": "[string] 服务包可访问的文件 URL" } }, "required": [ "fileUrl", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "fileUrl": "https://your.domain/files/report.pdf" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/cdn/downloadBigFile": { "post": { "tags": [ "CDN 文件" ], "summary": "下载大文件", "operationId": "cdn_downloadBigFile", "description": "\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "fileId": { "type": "string", "description": "[string] 大文件 id(*1* 开头)" }, "fileName": { "type": "string", "description": "[string] 文件名" } }, "required": [ "fileId", "fileName", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "fileId": "*1*<大文件 id>", "fileName": "random_20mb_20260727.txt" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/cdn/getBigFileDownloadUrl": { "post": { "tags": [ "CDN 文件" ], "summary": "获取大文件下载url", "operationId": "cdn_getBigFileDownloadUrl", "description": "返回可直接下载的 url。\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "fileId": { "type": "string", "description": "[string] 大文件 id" }, "fileName": { "type": "string", "description": "[string] 文件名" } }, "required": [ "fileId", "fileName", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "fileId": "*1*<大文件 id>", "fileName": "random_20mb_20260727.txt" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/label/sync": { "post": { "tags": [ "标签" ], "summary": "同步标签(个/企)", "operationId": "label_sync", "description": "【2026-09-06 实测】实测与文档示例结构一致(seq/labelItems/hasNext),接口实际可用(mark=dev 为文档口径)。 | 返回标签组(dataType 2)与标签(dataType 1)两类实体;hasNext=true 表示还有数据,用新 seq 继续拉。建议持久化最新 seq。企业标签变更推送 contentType 2185，个人标签变更推送 2186。\n\n> `syncType` 与 `labelType` 都是 `1` 企业标签、`2` 个人标签；`dataType` 为 `1` 表示标签、`2` 表示标签组。企业标签变更推送 `contentType 2185`，个人标签变更推送 `2186`。\n\n> 【注意】服务端标记该接口为开发中，响应结构可能变动。\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "seq": { "type": "integer", "format": "int64", "description": "[int64] 首次传 0 取全量;后续传响应返回的最新 seq 增量拉取" }, "syncType": { "type": "integer", "format": "int64", "description": "标签类型：`1` 企业标签、`2` 个人标签" } }, "required": [ "seq", "syncType", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "seq": 0, "syncType": 2 } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "properties": { "seq": { "type": "integer", "format": "int64", "description": "同步游标(增量翻页位置)" }, "labelItems": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "integer", "format": "int64", "description": "操作:`1` 新增 / `2` 删除 / `3` 修改" }, "label": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "记录/文件业务标识" }, "name": { "type": "string", "description": "昵称 / 显示名" }, "dataType": { "type": "integer", "format": "int64", "description": "数据类型：`1` 标签、`2` 标签组" }, "bDeleted": { "type": "integer", "format": "int64", "description": "是否已删除(0/1)" }, "labelGroupId": { "type": "integer", "format": "int64", "description": "所属标签组 id" }, "createTime": { "type": "integer", "format": "int64", "description": "建立 / 更新时间戳(秒)" }, "labelType": { "type": "integer", "format": "int64", "description": "标签类型：`1` 企业标签、`2` 个人标签" }, "businessType": { "type": "integer", "format": "int64", "description": "业务类型 / 排序 / 服务组 id(原样回传)" }, "order": { "type": "integer", "format": "int64", "description": "业务类型 / 排序 / 服务组 id(原样回传)" }, "serviceGroupId": { "type": "integer", "format": "int64", "description": "业务类型 / 排序 / 服务组 id(原样回传)" } }, "description": "完整标签对象(须原样取自 `/api/label/sync`)" } }, "description": "标签/标签组条目列表" }, "description": "标签/标签组条目列表" }, "hasNext": { "type": "boolean", "description": "是否还有下一页" } }, "description": "业务数据(结构以实测为准)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": { "seq": 7807081, "labelItems": [ { "op": 3, "label": { "id": 14073750612004751, "name": "客户等级", "dataType": 2, "bDeleted": 0, "labelGroupId": 0, "createTime": 1781337439, "labelType": 1, "businessType": 0, "order": 0, "serviceGroupId": 0 } }, { "op": 3, "label": { "id": 14073750612004752, "name": "一般", "dataType": 1, "bDeleted": 0, "labelGroupId": 14073750612004751, "createTime": 1781337439, "labelType": 1, "businessType": 0, "order": 0, "serviceGroupId": 0 } } ], "hasNext": false }, "detail": "", "message": "ok", "time": "2026-08-28 09:26:33" } } } } } } }, "/api/label/operate": { "post": { "tags": [ "标签" ], "summary": "操作标签/标签组(个/企)", "operationId": "label_operate", "description": "op=1 新增:id=0 且 createTime=0;op=2 删除:完整提交 label 对象(个人标签组不可删);op=3 修改:仅可改 name,其余字段原样提交。个人标签不支持新增标签组,仅企业标签组支持。\n\n> 【注意】服务端标记该接口为开发中，响应结构可能变动。\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "opScene": { "type": "integer", "format": "int64", "description": "[int] 操作场景:仅新增企业标签组传 1,其余固定 2" }, "labelType": { "type": "integer", "format": "int64", "description": "标签类型：`1` 企业标签、`2` 个人标签" }, "operItems": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "integer", "format": "int64", "description": "操作:`1` 新增 / `2` 删除 / `3` 修改" }, "label": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "标签 id" }, "name": { "type": "string", "description": "标签名" }, "dataType": { "type": "integer", "format": "int64", "description": "数据类型：`1` 标签、`2` 标签组" }, "bDeleted": { "type": "integer", "format": "int64", "description": "是否已删除(0/1)" }, "labelGroupId": { "type": "integer", "format": "int64", "description": "所属标签组 id" }, "createTime": { "type": "integer", "format": "int64", "description": "建立 / 更新时间戳(秒)" }, "labelType": { "type": "integer", "format": "int64", "description": "标签类型：`1` 企业标签、`2` 个人标签" }, "businessType": { "type": "integer", "format": "int64", "description": "业务类型 / 排序 / 服务组 id(原样回传)" }, "order": { "type": "integer", "format": "int64", "description": "业务类型 / 排序 / 服务组 id(原样回传)" }, "serviceGroupId": { "type": "integer", "format": "int64", "description": "业务类型 / 排序 / 服务组 id(原样回传)" } }, "description": "完整标签对象(须原样取自 `/api/label/sync`)" } }, "description": "标签操作项列表" }, "description": "标签操作项列表" } }, "required": [ "opScene", "labelType", "operItems", "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "opScene": 2, "labelType": 1, "operItems": [ { "op": 2, "label": { "id": 14073752025997020, "name": "老王", "dataType": 1, "bDeleted": 0, "labelGroupId": 14073751126007793, "createTime": 1787907966, "labelType": 1, "businessType": 0, "order": 0, "serviceGroupId": 0 } } ] } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/personal/updateInfo": { "post": { "tags": [ "个人信息" ], "summary": "更新个人信息", "operationId": "personal_updateInfo", "description": "\n\n**安全级别**: write", "x-safety": "write", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" }, "gender": { "type": "integer", "format": "int64", "description": "[int] 1 男 / 2 女" }, "name": { "type": "string", "description": "[string] 姓名" }, "alias": { "type": "string", "description": "[string] 别名" }, "phone": { "type": "string", "description": "电话(外部对象常为空)" }, "xcxCorpAddress": { "type": "string", "description": "【2026-09-11 实测新增】 小程序名片-企业地址,base64 编码(如 `5rWZ5rGf5aSn5aSP...`→「浙江大夏...」)。" }, "email": { "type": "string", "description": "邮箱" } }, "required": [ "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx", "gender": 1, "name": "哈哈哈", "alias": "测试下", "phone": "12313-1231", "xcxCorpAddress": "浙江大夏", "email": "903809901@qq.com" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/personal/getQrcode": { "post": { "tags": [ "个人信息" ], "summary": "获取个人二维码", "operationId": "personal_getQrcode", "description": "我的企微名片二维码。\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" } }, "required": [ "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "description": "响应数据(结构以实测为准,文档未给时为空)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": {}, "detail": "", "message": "ok", "time": "2026-09-11 10:00:00" } } } } } } }, "/api/personal/getInfo": { "post": { "tags": [ "个人信息" ], "summary": "获取个人信息", "operationId": "personal_getInfo", "description": "【2026-09-06 实测】账号 id = uin(int64),名字 = name,头像 = iconUrl,企业 = corpId(数字);已脱敏 mobile/realName。 | 当前登录账号资料(用于实例展示昵称/头像/企业名)。\n\n**安全级别**: read", "x-safety": "read", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token 鉴权(在控制台「应用凭证」获取)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appid": { "type": "string", "description": "设备(实例)appid,标识操作哪个已登录账号" } }, "required": [ "appid" ] }, "example": { "appid": "we_xxxxxxxxxxxxxxx" } } } }, "responses": { "200": { "description": "统一封套 {code,data,detail,message,time};code=0 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64", "description": "统一封套状态码:0=成功,负数=失败" }, "data": { "type": "object", "properties": { "uin": { "type": "integer", "format": "int64", "description": "用户唯一 id(int64,注意精度)" }, "name": { "type": "string", "description": "昵称 / 显示名" }, "emailAddr": { "type": "string", "description": "个人邮箱" }, "birthday": { "type": "string", "description": "生日 `YYYY-MM-DD HH:MM:SS`" }, "mobile": { "type": "string", "description": "手机号(示例已脱敏)" }, "phone": { "type": "string", "description": "电话(外部对象常为空)" }, "job": { "type": "string", "description": "职位 / 职务" }, "number": { "type": "string", "description": "工号" }, "gender": { "type": "integer", "format": "int64", "description": "性别(1 男 / 2 女)" }, "iconUrl": { "type": "string", "description": "头像 url" }, "corpId": { "type": "integer", "format": "int64", "description": "所属企业唯一 id(int64)" }, "attr": { "type": "integer", "format": "int64", "description": "属性位掩码(bitmask),各 bit 含义待确认" }, "dispOrder": { "type": "integer", "format": "int64", "description": "通讯录 / 部门内显示排序" }, "bizUin": { "type": "integer", "format": "int64", "description": "企业 uin,含义待确认" }, "position": { "type": "string", "description": "职位 / 职务" }, "alias": { "type": "string", "description": "别名 / 花名" }, "mainPartyId": { "type": "integer", "format": "int64", "description": "主部门 id" }, "gid": { "type": "integer", "format": "int64", "description": "全局 id(跨企业标识),含义待确认" }, "isNameVerified": { "type": "boolean", "description": "是否已实名认证" }, "internationCode": { "type": "string", "description": "国际区号,如 `86`" }, "bindEmailStatus": { "type": "integer", "format": "int64", "description": "邮箱绑定状态(观测到 `2`=已绑定 / `1`),枚举待确认" }, "englishName": { "type": "string", "description": "英文名" }, "customInfo": { "type": "object", "properties": {}, "description": "自定义字段集合(常为空对象)" }, "nameVerifyStatus": { "type": "integer", "format": "int64", "description": "实名认证状态(观测 `1`)" }, "realName": { "type": "string", "description": "实名(示例已脱敏)" }, "vCorpUseStatus": { "type": "integer", "format": "int64", "description": "企业使用状态(观测 `1000`),含义待确认" }, "holidayInfo": { "type": "object", "properties": { "holidayStatus": { "type": "integer", "format": "int64", "description": "假期状态 / 新版假期状态" }, "holidayDesc": { "type": "string", "description": "假期描述文案" }, "oldHolidayIconIndex": { "type": "integer", "format": "int64", "description": "假期头像挂件索引 / 旧索引" }, "createTime": { "type": "integer", "format": "int64", "description": "建立 / 更新时间戳(秒)" }, "holidayInfoId": { "type": "integer", "format": "int64", "description": "假期信息 id" }, "holidayIconIndex": { "type": "integer", "format": "int64", "description": "假期头像挂件索引 / 旧索引" }, "holidayGenerateSrc": { "type": "integer", "format": "int64", "description": "假期来源(含义待确认)" }, "holidayStatusNew": { "type": "integer", "format": "int64", "description": "假期状态 / 新版假期状态" }, "vacationSyncType": { "type": "integer", "format": "int64", "description": "【2026-09-11 实测新增】 `holidayInfo` 内新增字段:休假同步类型(实测 `0`)。" } }, "description": "休假信息(`holidayStatus`/`holidayDesc`/... )" }, "xcxStyle": { "type": "integer", "format": "int64", "description": "小程序名片样式,含义待确认" }, "xcxCorpAddress": { "type": "string", "description": "【2026-09-11 实测新增】 小程序名片-企业地址,base64 编码(如 `5rWZ5rGf5aSn5aSP...`→「浙江大夏...」)。" }, "attr2": { "type": "integer", "format": "int64", "description": "属性位掩码(bitmask),各 bit 含义待确认" }, "tencentInfo": { "type": "object", "properties": {}, "description": "腾讯生态相关(常为空对象)" }, "isSyncInnerPosition": { "type": "boolean", "description": "是否同步内部职位" }, "unionId": { "type": "string", "description": "微信 unionId(跨应用用户标识)" }, "vCode": { "type": "string", "description": "名片/验证码(形如 `vc31f1...`)" }, "personalWorkType": { "type": "integer", "format": "int64", "description": "个人工作类型,含义待确认" }, "superiors": { "type": "array", "items": { "type": "object", "properties": {}, "description": "【2026-09-11 实测新增】 上级链(汇报关系),元素为对象,实测样本中均为 `[{}]`(空对象占位)。" }, "description": "【2026-09-11 实测新增】 上级链(汇报关系),元素为对象,实测样本中均为 `[{}]`(空对象占位)。" }, "bizMail": { "type": "string", "description": "企业邮箱" }, "attr3": { "type": "integer", "format": "int64", "description": "属性位掩码(bitmask),各 bit 含义待确认" }, "collegeIdentity": { "type": "integer", "format": "int64", "description": "学校 / 高校身份类型,含义待确认" }, "mobileAreaCode": { "type": "integer", "format": "int64", "description": "手机区号,含义待确认(常为 0)" } }, "description": "业务数据(结构以实测为准)" }, "detail": { "type": "string", "description": "附加明细,通常为空" }, "message": { "type": "string", "description": "文案:成功为 ok;失败形如 -码|描述" }, "time": { "type": "string", "description": "服务端处理时间 YYYY-MM-DD HH:MM:SS" } } }, "example": { "code": 0, "data": { "uin": 1688855440457534, "name": "哈哈哈", "emailAddr": "", "birthday": "2000-09-01 12:00:00", "mobile": "177****2663", "phone": "", "job": "", "number": "", "gender": 1, "iconUrl": "https://wework.qpic.cn/wwpic/450926_GsZ9MQliR-K3gHt_1697180185/0", "corpId": 1970325156983916, "attr": 177209664, "dispOrder": 0, "bizUin": 1, "position": "", "alias": "测试下", "mainPartyId": 1688857997391345, "gid": 2251800393707302, "isNameVerified": true, "internationCode": "86", "bindEmailStatus": 1, "englishName": "ZhangZhiXing", "customInfo": {}, "nameVerifyStatus": 1, "realName": "张**", "vCorpUseStatus": 1000, "holidayInfo": { "holidayStatus": 0, "holidayDesc": "", "oldHolidayIconIndex": 0, "createTime": 0, "holidayInfoId": 0, "holidayIconIndex": 0, "holidayGenerateSrc": 0, "holidayStatusNew": 0, "vacationSyncType": 0 }, "xcxStyle": 0, "xcxCorpAddress": "5rWZ5rGf5aSn5aSPMjEzMjEzMjEzMjEzMTIzMTI=", "attr2": 1041367168, "tencentInfo": {}, "isSyncInnerPosition": true, "unionId": "ozynqslW2bdBrXxDMs3NgT8qvpLw", "vCode": "vcbda9d6adafd0a2ef", "personalWorkType": 0, "superiors": [ {} ], "bizMail": "zhangzhixing@xzwbtwlkjyxgs.wecom.work", "attr3": 0, "collegeIdentity": 0, "mobileAreaCode": 0 }, "detail": "", "message": "ok", "time": "2026-09-06 11:26:14" } } } } } } }, "/webhook/set": { "post": { "tags": [ "回调配置(Webhook)" ], "summary": "设置/更新回调地址(客户自助)", "description": "客户用 App Token 设置自己的回调(Webhook)地址;系统收到长链回调后按此转发推送。每个 App 一个回调,重复调用为更新。\n\n- `url` 必填(http/https);`events` 不填=订阅全部事件;`secret` 不填自动生成。\n- secret 明文仅创建时返回一次,用于校验推送头 X-Eyun-Signature: sha256=", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token(与业务接口同一套鉴权)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "你的回调接收地址(http/https)" }, "events": { "type": "array", "items": { "type": "string" }, "description": "订阅事件名;不填=全部(见 /webhook/event-types)" }, "secret": { "type": "string", "description": "签名密钥;不填自动生成" }, "status": { "type": "string", "description": "active|paused" } } }, "example": { "url": "https://your.domain/hook", "events": [ "message.received", "friend.added" ] } } } }, "responses": { "200": { "description": "{code:0, data, message}", "content": { "application/json": { "example": { "code": 0, "data": { "webhook": { "id": "whk_…", "name": "OpenAPI 回调", "url": "https://your.domain/hook", "events": [ "message.received", "friend.added", "friend.deleted", "contact.modified", "instance.online", "instance.offline" ], "status": "active", "signingEnabled": true }, "secret": "whs_首次返回一次" }, "message": "ok" } } } } } } }, "/webhook/get": { "post": { "tags": [ "回调配置(Webhook)" ], "summary": "查询当前回调配置", "description": "返回本 App 当前的回调配置(未设置则 webhook 为 null)。", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token(与业务接口同一套鉴权)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "responses": { "200": { "description": "{code:0, data, message}", "content": { "application/json": { "example": { "code": 0, "data": { "webhook": { "id": "whk_…", "name": "OpenAPI 回调", "url": "https://your.domain/hook", "events": [ "message.received", "friend.added", "friend.deleted", "contact.modified", "instance.online", "instance.offline" ], "status": "active", "signingEnabled": true } }, "message": "ok" } } } } } } }, "/webhook/delete": { "post": { "tags": [ "回调配置(Webhook)" ], "summary": "删除回调配置", "description": "删除本 App 的回调;删除后系统不再推送(可重新 set)。", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token(与业务接口同一套鉴权)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "responses": { "200": { "description": "{code:0, data, message}", "content": { "application/json": { "example": { "code": 0, "data": { "deleted": true }, "message": "ok" } } } } } } }, "/webhook/test": { "post": { "tags": [ "回调配置(Webhook)" ], "summary": "测试投递", "description": "向当前回调地址推送一条 webhook.test 事件，返回推送结果（HTTP 状态/响应片段）。", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token(与业务接口同一套鉴权)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "responses": { "200": { "description": "{code:0, data, message}", "content": { "application/json": { "example": { "code": 0, "data": { "ok": true, "eventType": "webhook.test", "httpStatus": 200 }, "message": "ok" } } } } } } }, "/webhook/event-types": { "post": { "tags": [ "回调配置(Webhook)" ], "summary": "可订阅事件列表", "description": "返回可订阅的事件类型(message.received / friend.added / friend.deleted / contact.modified / instance.online / instance.offline)。", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer eyk_<你的 App Token>", "description": "App Token(与业务接口同一套鉴权)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "responses": { "200": { "description": "{code:0, data, message}", "content": { "application/json": { "example": { "code": 0, "data": { "items": [ { "name": "message.received", "category": "", "description": "" }, { "name": "friend.added", "category": "", "description": "" }, { "name": "friend.deleted", "category": "", "description": "" }, { "name": "contact.modified", "category": "", "description": "" }, { "name": "instance.online", "category": "", "description": "" }, { "name": "instance.offline", "category": "", "description": "" } ] }, "message": "ok" } } } } } } } } }