API 参考

Eyun API 使用 HTTP POST 和 JSON 完成微信实例登录、消息收发、联系人协作与内容运营。首次接入先在控制台跑通真实消息，再把同一个调用凭证和实例 wId 接入后端。

与企业微信 API 的关系

本页是微信个人号 API。要接企业微信里的客户、客户群与企业成员，请看并列的企业微信 API 文档，凭证与实例互不通用。

	微信个人号 API	企业微信 API
接入对象	个人微信账号的好友与群	企业外部联系人（客户）、客户群与企业成员
开通方式	控制台自助开通，7 天免费试用	企微控制台自助开通，可以试用
API 调试	个人微信 API 调试	企业微信在线调试
实例标识	`wId`	`appid`
路径前缀	`/…`	`/wx-api/api/<模块>/…`

接入状态

你已经完成	接下来做什么
还没有开通	按快速开始开通并保存调用凭证
已开通，但微信未登录	按接入微信继续
微信已在线	在 API 调试给文件传输助手发一条消息，再按配置回调地址确认接收服务收到消息
手机已收到测试消息	用代码调用接口，再选择下方业务接口

请求约定

项目	约定
Base URL	从控制台文档中心复制完整 API Base URL，保留路径前缀，填入 `{BASE_URL}`
请求方法	除特殊说明外均为 `POST`
请求格式	`Content-Type: application/json`
推荐认证	`Authorization: Bearer <你的调用凭证>`
成功码	`"code": "1000"`，只有它算成功
失败码	通常是 `"1001"`；群、视频号、消息资源下载等接口在 `wId` 无效或未登录时返回 `"8000"`

新默认应用在控制台「应用凭证」页领取一次完整调用凭证并保存；已有应用使用自己保存的完整凭证，掩码不能用于调用。采用开发者账号密码鉴权时，按调用凭证中的对应流程取得凭证。

bash

curl -X POST "{BASE_URL}/sendText" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <你的调用凭证>" \
  -d '{
    "wId": "你的登录实例ID",
    "wcId": "filehelper",
    "content": "Hello from Eyun"
  }'

通用响应

json

{
  "code": "1000",
  "message": "成功",
  "data": {}
}

code = "1000" 只表示接口请求成功。查询在线状态、异步任务等接口还需要继续判断 data 中的业务状态，例如在线状态以 data.isOnline 为准。

判断结果只看 code 是不是 "1000"，不要写成「等于 "1001" 才算失败」，否则会漏掉 "8000"。失败原因写在 message 里，最常见的几种见常见失败信息。

newMsgId 是大整数

newMsgId 最长 19 位，超过 JavaScript 能精确表示的整数范围。Node.js 和前端直接 JSON.parse，末几位会变，拿它撤回消息或去重就对不上。用 json-bigint 这类库解析，或按字符串保存和比较；Go 不要解析到 interface{}，用 int64 字段。Java 的 long、Python 的 int 不受影响。

登录后先同步基础数据

微信登录成功后，建议按下面的顺序把联系人和群同步到自己的数据库：

顺序	调用	说明
1	初始化通讯录	同步好友、公众号等基础联系人数据
2	获取通讯录列表	拿到好友、群聊、公众号的 ID 列表，群聊在 `data.chatrooms`
3	按需查详情	联系人、群、群成员的详情按业务需要再调

列表接口主要返回 ID。把 ID 存进数据库，需要展示昵称、头像、备注、群成员时，再调对应的详情接口补充。

接口分类

认证与实例

目标	推荐入口
了解调用凭证和登录方式	调用凭证
在自己后台集成登录	Step 1：开发者账号鉴权 → Step 2：获取二维码 → Step 3：执行登录
查询与恢复实例	登录状态 · 断线重连

消息与 Webhook

目标	推荐入口
发送消息	文本 · 图片 · 文件 · 视频 · 小程序
接收事件	设置回调 · 事件索引 · 回调字典
转发已有消息	文件 · 图片 · 视频

联系人、群聊与标签

模块	常用接口
联系人	初始化通讯录 · 联系人列表 · 联系人详情
好友操作	搜索 · 添加 · 备注
群聊	创建群 · 群详情 · 群成员
标签	创建 · 修改 · 列表

朋友圈、视频号与收藏

模块	常用接口
朋友圈	查询 · 发文字 · 发图片 · 互动
视频号	搜索 · 主页 · 发布 · 私信
收藏	列表 · 详情 · 删除

媒体与文件

目标	常用接口
下载消息资源	文件 · 图片 · 语音 · 视频
CDN	下载 · 上传图片 · 上传视频

错误与诊断

目标	常用入口
网络调整	设置代理 IP · Aid 本地代理
排查问题	错误码与排查 · 常见问题

上线前

完成接口联调后，核对 API 使用与安全、Webhook 可靠性和上线检查清单。

API 参考 ​

与企业微信 API 的关系 ​

接入状态 ​

请求约定 ​

通用响应 ​

登录后先同步基础数据 ​

接口分类 ​

认证与实例 ​

消息与 Webhook ​

联系人、群聊与标签 ​

朋友圈、视频号与收藏 ​

媒体与文件 ​

错误与诊断 ​

上线前 ​