Appearance
API 参考
按模块列出全部接口，每个能力一个路径，全部 POST + JSON。首次接入先在控制台领取凭证、扫码并测试收发，再按文档将请求接入代码。调用约定见快速开始。
协议版本 2026.09.11，与 openapi.json 一致，可导入 Apifox / Swagger。
请求约定
| 项 | 约定 |
|---|---|
| 方法 | POST |
| 请求头 | Authorization: Bearer <你的调用凭证> |
| 请求地址 | {BASE_URL} 保留 /wx-api，业务路径接 /api/…，回调配置接 /webhook/… |
| 返回格式 | {code, data, detail, message, time} |
| 成功判断 | code=0 表示调用成功；登录、重连及测试推送还需核对操作结果，见错误码 |
全部接口
表格说明：路径、实测日期标记、安全级别
接口名下方保留含 /wx-api 的完整路径，供核对路由。请求示例已按完整 API Base 拼接，不要再添加 /wx-api。
带「实测 日期」标记的接口，表示该日做过接口测试；未标注不代表未测试。
安全级别是协议自带的分类：只读不改变任何数据；写操作会产生消息、资料或关系变化；高风险指删除、解散、退出这类不可逆动作，调用前应有二次确认。
登录
扫码登录、验证码、断线重连、退出。见登录模块。
| 接口 | 用途 | 安全级别 |
|---|---|---|
获取二维码/wx-api/api/login/getQr | 获取登录二维码，同时返回这次二维码的 uuid，用于后续查询扫码进度。 | 写操作 |
检测二维码/wx-api/api/login/checkQr | 查询是否已扫码、是否需要验证码以及是否登录成功；登录成功时返回当前账号信息。 | 写操作 |
提交验证码/wx-api/api/login/submitQrCode | 当 checkQr 返回 status:10（企微要求二次验证）时，提交手机端显示的 6 位验证码。 | 写操作 |
断线重连/wx-api/api/login/reconnect | 收到错误码 -11001（企微连接断开）时调用，判断账号是否仍在线并尝试恢复登录。 | 写操作 |
退出登录/wx-api/api/login/logout | 主动退出该设备当前登录的企微账号。 | 高风险 |
消息
发送各类消息、补拉消息、撤回、群发。见消息模块。
| 接口 | 用途 | 安全级别 |
|---|---|---|
同步消息/wx-api/api/message/sync | 主动拉取消息。 | 只读 |
发送文本消息/wx-api/api/message/sendText | 发送纯文本消息。 | 写操作 |
发送富文本消息/wx-api/api/message/sendRichText | 发送带表情、@ 成员的富文本；群聊 @ 功能通过本接口实现。 | 写操作 |
发送语音消息/wx-api/api/message/sendVoice | 发送语音（silk 格式）。 | 写操作 |
发送图片消息/wx-api/api/message/sendImage | 发送图片。 | 写操作 |
发送视频消息/wx-api/api/message/sendVideo | 发送视频（小视频）。 | 写操作 |
发送文件消息/wx-api/api/message/sendFile | 发送普通文件（小文件）；大文件走 sendBigFile。 | 写操作 |
发送大文件/wx-api/api/message/sendBigFile | 发送超过 8MB 的文件：先用 cdn/uploadBigFile 上传，再把推送里下发的凭证填进 content。 | 写操作 |
发送链接卡片（含视频号）/wx-api/api/message/sendLink | 发送图文链接卡片；sph_feed_h5_message 子对象用于视频号卡片。 | 写操作 |
发送名片消息/wx-api/api/message/sendNameCard | 把某个用户的名片发到会话。 | 写操作 |
发送 GIF 消息/wx-api/api/message/sendGif | 发送 GIF 动图表情。 | 写操作 |
发送位置消息/wx-api/api/message/sendLocation | 发送地理位置卡片。 | 写操作 |
发送小程序/wx-api/api/message/sendMiniProgram | 发送小程序卡片。 | 写操作 |
撤回消息/wx-api/api/message/revoke | 撤回一条已发送的消息。 | 高风险 |
获取群发素材列表/wx-api/api/message/getMaterialList | 拉取群发助手预置的素材（文案 + 附件组合），供群发时按 materialId 引用。 | 只读 |
群发消息/wx-api/api/message/groupSend | 向一批客户或客户群批量发送消息。 | 写操作 |
获取待发送群发列表/wx-api/api/message/getPendingGroupSendList | 拉取「待发送」队列（企微侧已排入、尚未真正下发的群发任务）。 | 只读 |
发送待发送群发/wx-api/api/message/groupSendPending | 把「待发送」队列里的某条任务真正下发。 | 写操作 |
获取群发记录/wx-api/api/message/getGroupSendRecord | 查询本账号历史群发记录（含内容、触达统计、发送范围）。 | 只读 |
联系人
通讯录同步、详情、搜索、加好友、备注、标签。见联系人模块。
| 接口 | 用途 | 安全级别 |
|---|---|---|
同步通讯录 ID 列表/wx-api/api/contact/getSyncList | 拉取内部通讯录的成员和部门 ID 列表，以及做增量同步用的版本号，这是通讯录同步的第一步。 | 只读 |
批量获取通讯录详细信息/wx-api/api/contact/fetchUsersProfileBatch | 把 getSyncList 的节点列表换成每个节点的详细资料（成员资料 / 部门信息）。 | 只读 |
获取用户详情/wx-api/api/contact/getUserProfileDetail | 按用户 id 列表直接查最全的用户资料（内部成员或外部联系人均可）。 | 只读 |
手机号搜索/wx-api/api/contact/phoneNumberSearch | 按手机号搜索用户，拿到添加好友所需的票据（wxTicket）与身份（openid / uin / corpId），供后续加好友接口使用。 | 只读 |
通过手机号添加个微/wx-api/api/contact/phoneNumberAddWechat | 用 phoneNumberSearch 拿到的票据，向对方的个人微信发起好友申请。 | 写操作 |
通过手机号添加企微/wx-api/api/contact/phoneNumberAddWework | 用 phoneNumberSearch 拿到的企微身份与票据，向对方的企业微信发起好友/客户申请。 | 写操作 |
同意新客户/wx-api/api/contact/agreeToNewCustomer | 对方主动申请添加你为好友/客户时，调用本接口同意。 | 写操作 |
更新外部联系人信息/wx-api/api/contact/updateExternalContactInfo | 修改某个外部联系人（客户）的备注、公司、真实备注、备注手机号等。 | 写操作 |
删除联系人/wx-api/api/contact/delete | 删除一个联系人（解除好友关系）。 | 高风险 |
设置同事备注/wx-api/api/contact/setColleagueRemark | 给内部成员（同事）设置备注 / 描述。 | 写操作 |
添加名片/wx-api/api/contact/addCard | 通过收到的「个人名片消息」添加对方为好友。 | 写操作 |
添加群成员为好友/wx-api/api/contact/addRoomMember | 把群内某成员添加为自己的好友（不是把人拉进群）。 | 写操作 |
同步外部联系人/wx-api/api/contact/syncExternal | 增量同步外部联系人（客户）数据；收到回调 contentType=2131（外部联系人变更）后调用拉增量。 | 只读 |
更新用户标签/wx-api/api/contact/updateLabel | 给某个用户打 / 去 / 改标签（操作的是「用户 ↔ 标签」的关联）。 | 写操作 |
群
建群、资料、成员、群管理开关、退群与解散。见群模块。
| 接口 | 用途 | 安全级别 |
|---|---|---|
获取群资料/wx-api/api/room/getInfo | 查询单个群的资料——群名、群主、建群时间、成员列表（vid / 入群时间 / 邀请人 / 备注等）。 | 只读 |
移除群成员/wx-api/api/room/delMember | 把一个或多个成员移出群（踢人）。 | 高风险 |
添加群成员/wx-api/api/room/addMember | 邀请一个或多个用户进群（拉人入群）。 | 写操作 |
设置群名/wx-api/api/room/setName | 修改群名称。 | 写操作 |
获取群二维码/wx-api/api/room/getQrCode | 获取群的入群二维码（返回二维码图片 base64 + 群头像 url）。 | 只读 |
修改群公告/wx-api/api/room/setNotice | 设置 / 修改群公告文本。 | 写操作 |
设置管理员/wx-api/api/room/setAdmin | 把某成员设为群管理员，或取消其管理员身份。 | 写操作 |
转让群主/wx-api/api/room/changeOwner | 把群主身份转让给另一名成员。 | 高风险 |
创建客户群/wx-api/api/room/create | 创建一个新的（空）客户群，返回新群 roomId 与邀请卡片信息；随后用 addMember 拉人。 | 写操作 |
修改我在群内的昵称/wx-api/api/room/setMyNickname | 修改当前账号在指定群里的群昵称，只影响你在这个群的显示名。 | 写操作 |
保存群到通讯录/wx-api/api/room/saveToContact | 把群「保存到通讯录 / 从通讯录移除」（开关）。 | 写操作 |
获取我的客户群列表/wx-api/api/room/getMyCustomerGroupList | 分页拉取当前账号名下的客户群列表，这是拿到 roomId 的主要途径。 | 只读 |
会话置顶 / 取消置顶/wx-api/api/room/top | 把会话（群或联系人）置顶或取消置顶。 | 写操作 |
退出群聊/wx-api/api/room/quit | 让当前账号退出某个群。 | 高风险 |
开启 / 关闭入群确认/wx-api/api/room/inviteConfirm | 开启 / 关闭「入群邀请需群主确认」。 | 写操作 |
禁止成员改群名/wx-api/api/room/forbidRename | 开启 / 关闭「仅群主可修改群名」（禁止普通成员改群名）。 | 写操作 |
禁止群成员互加好友/wx-api/api/room/forbidMutualAdd | 开启 / 关闭「禁止群成员互相添加好友 / 互相拉人」。 | 写操作 |
解散群聊/wx-api/api/room/disband | 群主解散整个群（所有成员被移出，群不复存在）。 | 高风险 |
设置群备注/wx-api/api/room/setRemark | 给群设置备注，只对当前账号生效，不会改群名。 | 写操作 |
客户朋友圈
发圈、列表、详情、点赞、评论、删除、签名。见客户朋友圈模块。
| 接口 | 用途 | 安全级别 |
|---|---|---|
发布朋友圈/wx-api/api/friend/sendSns | 用当前账号发一条客户朋友圈，支持纯文本 / 图文 / 视频 + 可见范围 + 位置。 | 写操作 |
获取朋友圈列表/wx-api/api/friend/getSnsList | 分页拉取本账号可见的朋友圈动态流（自己 + 客户）。 | 只读 |
设置朋友圈签名/wx-api/api/friend/setSnsSignature | 设置本账号的「朋友圈签名」（个性签名文案）。 | 写操作 |
朋友圈点赞/wx-api/api/friend/likeSns | 对某条朋友圈动态点赞 / 取消点赞。 | 写操作 |
获取朋友圈详情/wx-api/api/friend/getSnsDetails | 按单个 sid 查一条朋友圈动态的完整详情（含点赞、评论、已删评论、可见范围）。 | 只读 |
发布朋友圈评论/wx-api/api/friend/commentSns | 对某条朋友圈动态发评论，或对某条评论追评（回复）。 | 写操作 |
删除朋友圈评论/wx-api/api/friend/deleteSnsComment | 删除某条朋友圈动态下的一条评论。 | 高风险 |
删除朋友圈/wx-api/api/friend/deleteSns | 删除本账号自己发布的一条朋友圈动态。 | 高风险 |
CDN 文件
上传图片、视频、文件拿凭证，下载收到的文件，大文件收发。见CDN 文件模块。
| 接口 | 用途 | 安全级别 |
|---|---|---|
上传图片/wx-api/api/cdn/uploadImage | 发图片消息前先用它上传图片（base64），拿到图片凭证；sendMiniProgram 的封面图也用它上传。 | 写操作 |
上传视频/wx-api/api/cdn/uploadVideo | 发视频消息前先用它上传视频和封面图（base64），返回的 data 原样填进 message/sendVideo 的 content。 | 写操作 |
上传文件/wx-api/api/cdn/uploadFile | 发文件或语音消息前先用它上传文件（base64），语音传 .silk 文件；填进 message/sendFile 或 sendVoice 时，fileId、fileMd5、fileSize 要改名为 id、md5、size。 | 写操作 |
上传大文件/wx-api/api/cdn/uploadBigFile | base64 后超过 8MB 的文件，以及朋友圈的图片和视频，都用它上传：传文件的公网 URL，异步完成，凭证经推送下发。 | 写操作 |
下载媒体文件/wx-api/api/cdn/download | 下载收到的图片、视频、文件和语音：凭 fileId、fileType、aesKey 取回解密后的文件（base64）。 | 只读 |
按链接下载个微文件/wx-api/api/cdn/urlDownload | 个微（微信）侧的媒体只给了下载链接时，凭 url 与 aesKey 取回文件；有 fileId 的附件用 cdn/download。 | 只读 |
下载大文件/wx-api/api/cdn/downloadBigFile | 下载大文件（id 以 *1* 开头），来源是大文件消息或 uploadBigFile。 | 只读 |
获取大文件下载链接/wx-api/api/cdn/getBigFileDownloadUrl | 拿大文件的直接下载链接，交给浏览器或客户端自己下载，文件内容不经 Eyun 中转。 | 只读 |
标签
标签同步与操作。见标签模块。
| 接口 | 用途 | 安全级别 |
|---|---|---|
同步标签/wx-api/api/label/sync | 全量或增量拉取当前账号可见的标签组 + 标签清单（个人标签 / 企业标签两套）。 | 只读 |
操作标签或标签组/wx-api/api/label/operate | 新增 / 删除 / 修改标签或标签组。 | 写操作 |
个人信息
当前账号资料与二维码。见个人信息模块。
| 接口 | 用途 | 安全级别 |
|---|---|---|
更新个人信息/wx-api/api/personal/updateInfo | 修改当前登录账号的资料（昵称/别名/性别/电话/邮箱/小程序名片地址）。 | 写操作 |
获取个人二维码/wx-api/api/personal/getQrcode | 获取「我的企微名片二维码」图片（别人扫码加你）。 | 只读 |
获取个人信息/wx-api/api/personal/getInfo | 读取当前登录账号的资料：uin、名字、头像、企业等。 | 只读 |
回调配置
设置、查询、删除、测试回调地址，查看可订阅事件。见回调配置模块。
| 接口 | 用途 | 安全级别 |
|---|---|---|
设置或更新回调地址/wx-api/webhook/set | 用调用凭证设置你的回调地址；系统收到企微事件后按此地址推送给你。 | 写操作 |
查询当前回调配置/wx-api/webhook/get | 返回当前应用的回调配置（未设置则 webhook 为 null）。 | 只读 |
删除回调配置/wx-api/webhook/delete | 删除当前应用的回调；删除后系统不再推送（可重新 set）。 | 高风险 |
测试投递/wx-api/webhook/test | 向当前回调地址推送一条 webhook.test 事件，返回推送结果（HTTP 状态/响应片段）。 | 写操作 |
可订阅事件列表/wx-api/webhook/event-types | 返回可订阅的事件类型（message.received / friend.added / friend.deleted / contact.modified / instance.online / instance.offline）。 | 只读 |