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