Appearance
接口总览
按模块列出全部接口，每个能力一个路径，全部 POST + JSON。调用方式、鉴权与响应封套见概览的调用模型。
协议版本 2026.09.11，与 openapi.json 一致，可导入 Apifox / Swagger。
请求约定
| 项 | 约定 |
|---|---|
| 方法 | POST |
| 请求头 | Authorization: Bearer <你的 App Token> |
| 请求地址 | {BASE_URL} + 路径 |
| 响应封套 | {code, data, detail, message, time} |
| 成功判断 | code=0 表示调用成功；登录、重连及测试推送还需核对操作结果，见错误码 |
全部接口
图例：路径、实测日期标记、安全级别
接口名下方是完整接口路径；请求地址 = {BASE_URL} + 路径。
带「实测 日期」标记的接口，表示该日做过接口测试；未标注不代表未测试。
安全级别是协议自带的分类：只读不改变任何数据；写操作会产生消息、资料或关系变化；高风险指删除、解散、退出这类不可逆动作，调用前应有二次确认。
登录
扫码登录、验证码、断线重连、退出。见登录模块。
| 接口 | 用途 | 安全级别 |
|---|---|---|
获取二维码/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 | 发送大文件（超过 base64 直传上限）。 | 写操作 |
发送链接卡片消息（包含视频号）/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 | 拉取内部通讯录（成员 + 部门）的「节点列表 + 游标」，是通讯录同步的第一步。 | 只读 |
批量获取通讯录详细信息/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 文件模块。
| 接口 | 用途 | 安全级别 |
|---|---|---|
上传图片到 CDN/wx-api/api/cdn/uploadImage | 把本地图片（base64）上传到腾讯 CDN，拿到发图/下载所需的媒体凭证。 | 写操作 |
上传视频到 CDN/wx-api/api/cdn/uploadVideo | 上传小视频（base64）+ 封面图，拿到 message/sendVideo 所需凭证。 | 写操作 |
上传文件到 CDN/wx-api/api/cdn/uploadFile | 上传任意文件（base64），用于 message/sendFile；语音消息则先传 .silk 文件再走 sendVoice。 | 写操作 |
CDN 下载/wx-api/api/cdn/download | 凭「文件凭证」把 CDN 上的媒体解密取回本地（base64），用于下载收到的消息附件（图/视频/文件），或校验自己刚上传的媒体。 | 只读 |
上传大文件到 CDN/wx-api/api/cdn/uploadBigFile | 上传超出 base64 直传能力的大文件（视频/大附件）。 | 写操作 |
下载大文件/wx-api/api/cdn/downloadBigFile | 下载由 uploadBigFile 或大文件消息产生的大文件。 | 只读 |
获取大文件下载 URL/wx-api/api/cdn/getBigFileDownloadUrl | 不经 Eyun 服务器中转文件内容，而是拿一个可直接下载的 URL（适合大文件、交给浏览器/客户端自行下）。 | 只读 |
标签
标签同步与操作。见标签模块。
| 接口 | 用途 | 安全级别 |
|---|---|---|
同步标签/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 | 读取当前登录账号的资料全集——实例展示昵称/头像/企业名、消息 fromUser 匹配、判断实名等都靠它。 | 只读 |
回调配置
设置、查询、删除、测试回调地址，查看可订阅事件。见回调配置模块。
| 接口 | 用途 | 安全级别 |
|---|---|---|
设置或更新回调地址/wx-api/webhook/set | 用 App Token 设置你的回调地址；系统收到企微事件后按此地址推送给你。 | 写操作 |
查询当前回调配置/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）。 | 只读 |