Appearance
API 参考
Eyun 消息与客户协作 API 使用 JSON 请求和响应。
首次接入先完成快速开始：在控制台领取凭证、扫码登录、确认手机收信和 Webhook 接收，再把请求复制到代码。
基础信息
| 项目 | 说明 |
|---|---|
| Base URL | {BASE_URL}，从控制台文档中心的接口「调用信息」复制 API Base URL，保留其中的路径前缀 |
| 请求格式 | Content-Type: application/json |
| 认证方式 | 请求头携带 Authorization: Bearer <API 凭证> |
| 成功码 | "code": "1000" |
| 失败码 | "code": "1001" |
TIP
新默认应用在应用凭证页领取一次完整 Auth 并保存。已有应用使用自己保存的完整凭证，列表中的掩码不能复制为 Auth。
通用请求约定
| 项目 | 约定 |
|---|---|
| 请求方法 | 除特殊说明外，接口均使用 POST |
| 请求体 | JSON 对象。无参数接口传 {} |
| 认证 | 除登录平台接口外，业务接口都需要请求头 Authorization |
| 实例标识 | 大多数微信能力接口需要传 wId |
| 联系人标识 | 好友、群聊、公众号等目标通常使用 wcId 或接口文档指定字段 |
单个接口怎么读
每个接口页按同一顺序组织：
- 看接口地址和前置条件，确认是否已经拿到
Authorization、wId、wcId。 - 对照请求参数，只传当前场景需要的字段。
- 复制请求示例完成联调。
- 先判断
code，再按响应字段判断业务结果。 - 遇到失败时，先看页面底部的验证与排查，再查 API 使用与安全。
通用响应结构
json
{
"code": "1000",
"message": "成功",
"data": {}
}| 字段 | 类型 | 说明 |
|---|---|---|
| code | string | 1000 表示接口调用成功，1001 表示接口调用失败 |
| message | string | 本次请求的反馈信息 |
| data | object / array / null | 业务数据。无返回数据时通常为 null |
不要只看 code
code = "1000" 表示请求成功，不等于业务对象已经达到目标状态。例如查询在线状态时，应以 data.isOnline 为准。
推荐接入顺序
| 阶段 | 目标 | 关键文档 |
|---|---|---|
| 1 | 完成控制台首次测试 | 登录账号与网络设置 |
| 2 | 后端正式调用 | 发送文本 |
| 3 | 后端自行完成登录 | 开发者账号鉴权 → 获取二维码 → 执行登录 |
| 4 | 接收消息事件 | 设置回调地址 |
| 5 | 上线前检查 | API 使用与安全 |
登录后初始化顺序
微信实例登录成功后，建议按以下顺序初始化基础数据：
| 顺序 | 操作 | 说明 |
|---|---|---|
| 1 | 初始化通讯录 | 同步好友、公众号和基础联系人数据 |
| 2 | 获取通讯录列表 | 获取好友、群聊、公众号 ID 列表 |
| 3 | 初始化群列表 | 同步已保存到通讯录的群聊 |
| 4 | 获取群列表 | 获取已保存群聊 ID |
| 5 | 按需获取详情 | 联系人详情、群详情、群成员详情按业务需要调用 |
TIP
通讯录和群列表接口主要返回 ID。业务系统应把 ID 入库，并按需调用详情接口补充昵称、头像、备注、群成员等展示信息。
核心概念
| 名称 | 含义 | 注意事项 |
|---|---|---|
Authorization | 开发者调用凭证 | API 凭证使用 Bearer eyk_... 格式放在请求头中 |
wId | 登录实例标识 | 每次登录可能变化，业务接口主要使用它 |
wcId | 微信 ID / 接收方 ID | 掉线重登传原 wcId；群聊 ID 通常以 @chatroom 结尾 |
aid | Aid 本地代理编号 | 可由 Windows / Android / Linux 版本提供；选择 Aid 作为登录网络时传入，登录期间 Aid 工具必须保持运行 |
messageType | Webhook 消息类型 | 接收回调时按此字段分发处理 |
newMsgId | 新消息 ID | 建议作为消息排重依据之一 |
接口分类
登录与实例
| 接口 | 说明 |
|---|---|
| 登录账号与网络设置 | 控制台兑换试用、登录实例、Playground 测试和后端调用 |
| 开发者账号鉴权（Step 1） | 后端自行完成登录时获取 Auth |
| 获取登录二维码（Step 2） | 生成微信扫码二维码，登录网络必须在平台代理、自定义代理、本地代理（Aid）中三选一 |
| Aid 本地代理部署 | Windows、Android、Linux 三种 Aid 节点的选型与部署说明 |
| 执行微信登录（Step 3） | 完成扫码确认，获取微信实例信息 |
| 二次登录 | 手机弹框确认方式重新登录 |
消息发送
| 接口 | 说明 |
|---|---|
| 发送文本 | 发送纯文本消息 |
| 发送图片 | 通过图片 URL 发送图片 |
| 发送文件 | 通过文件 URL 发送文件 |
| 发送文件 Base64 | 通过 Base64 发送文件 |
| 发送语音 | 发送语音消息 |
| 发送视频 | 发送视频消息 |
| 发送链接 | 发送链接卡片 |
| 发送名片 | 发送个人或公众号名片 |
| 发送动图 | 发送 Emoji / 动图 |
| 发送 App 消息 | 发送 App 消息 |
| 发送小程序 | 发送小程序卡片 |
| 群聊 @成员 | 在群聊中 @指定成员 |
| 撤回消息 | 撤回已发送消息 |
| 发送错误码 | 排查发送失败原因 |
消息转发
| 接口 | 说明 |
|---|---|
| 转发文件 | 转发已收到的文件 |
| 转发图片 | 转发已收到的图片 |
| 转发视频 | 转发已收到的视频 |
| 转发链接 | 转发链接消息 |
| 转发小程序 | 转发小程序消息 |
消息接收与资源下载
| 接口 | 说明 |
|---|---|
| 设置回调地址 | 配置 Webhook 推送地址 |
| 取消回调 | 停止消息推送 |
| 回调字段释义 | 优化版回调结构和 messageType 说明 |
| 原生回调释义 | 原生格式回调结构 |
| 下载文件 | 下载消息中的文件 |
| 下载图片 | 下载消息中的图片 |
| 下载语音 | 下载消息中的语音 |
| 下载 Emoji | 下载动图内容 |
| 异步下载视频 | 提交视频下载任务 |
| 查询视频下载结果 | 查询异步下载进度 |
联系人、群聊与标签
| 模块 | 常用接口 |
|---|---|
| 通讯录 | 初始化通讯录、获取通讯录列表、获取联系人详情、获取联系人详情（完整版） |
| 好友操作 | 搜索好友、添加好友、同意好友、删除好友 |
| 好友设置 | 修改备注、好友权限、置顶、免打扰 |
| 群聊管理 | 创建群聊、添加成员、邀请成员、移除成员 |
| 群聊信息 | 群详情、群成员详情、群二维码、群公告 |
| 标签管理 | 创建标签、修改标签、删除标签、标签列表 |
朋友圈、视频号与收藏夹
| 模块 | 常用接口 |
|---|---|
| 朋友圈发布 | 文字朋友圈、图片朋友圈、视频朋友圈、链接朋友圈 |
| 朋友圈互动 | 点赞、取消点赞、评论、删除评论 |
| 朋友圈查询 | 获取自己朋友圈、获取好友朋友圈、朋友圈详情 |
| 视频号 | 搜索视频号、用户主页、关注、发布视频 |
| 收藏夹 | 获取收藏列表、获取收藏内容、删除收藏 |
实例管理与高级功能
| 接口 | 说明 |
|---|---|
| 批量下线微信实例 | 下线微信实例 |
| 查询在线列表 | 查询当前在线微信实例 |
| 断线重连微信实例 | 手机端在线但平台离线时尝试恢复连接 |
| 查询在线状态 | 检查指定微信实例是否在线 |
| 动态设置代理 IP | 为微信实例设置代理 |
| CDN 资源下载 | 通过 CDN 下载资源 |
| CDN 图片上传 | 上传图片至 CDN |
| CDN 视频上传 | 上传视频至 CDN |