⭐ 5 分钟快速开始

接入目标：完成 Token 鉴权、微信登录、接口调用和 Webhook 接收，跑通“发送一条消息并收到一条回调”的最小闭环。

平台能力

WechatApi 通过标准 HTTP API 和 Webhook 提供微信能力。业务系统只需要维护好 wechat-token、appId 和业务对象 ID，即可调用消息、联系人、群聊、朋友圈及视频号等接口。

接入前准备

项目	获取位置	用途
`wechat-token`	管理后台 → 访问控制	所有 API 请求的统一鉴权 Header
`appId`	登录流程返回，或在管理后台完成登录后获取	标识一个微信登录终端
回调地址	由你的业务服务提供	接收好友消息、群消息和状态变更事件

wechat-token 与 appId 用途不同：前者代表接口访问权限，后者代表实际执行操作的微信终端。

推荐接入路径

步骤	要完成的事	完成标志
1	获取 `wechat-token`	可以正常通过接口鉴权
2	登录微信并保存 `appId`	登录接口返回成功，终端在线
3	获取联系人或群聊 ID	已取得目标 `wxid` 或 `@chatroom` ID
4	发送第一条文本消息	接口返回成功，客户端收到消息
5	配置 Webhook	业务服务能够收到并处理推送事件

1. 获取 `wechat-token`

登录管理后台，进入“访问控制”，复制可用 Token。后续请求统一携带：

2. 登录微信并保存 `appId`

可以在管理后台完成扫码登录，也可以使用接口完成登录流程：

调用获取登录二维码，取得 appId、uuid 和二维码；

用户扫码后调用执行登录查询状态；

登录成功后，保存 appId 与 wxid 的对应关系。

关键规则：同一微信再次登录或掉线恢复时，应复用原来的 appId，不要每次创建新的终端标识。

3. 验证终端是否在线

在调用业务接口前，可先用检查是否在线验证 appId：

接口返回后，请同时判断 HTTP 状态和响应中的 ret、msg、data。

4. 发送第一条消息

推荐先调用获取通讯录列表，取得好友 wxid 或群聊 ID，再调用发送文字消息。

获取联系人/群聊 ID → 发送文字消息 → 检查 ret 与 msg → 在客户端确认结果

第一次联调建议发送给文件传输助手或专用测试账号，避免误发到真实业务会话。

5. 配置 Webhook

需要接收消息、群聊变化或登录状态事件时，在管理后台配置公网可访问的回调地址。回调服务应先快速响应，再异步处理业务逻辑。

详细配置、事件字段与示例见消息回调与事件参考。

最小闭环

获取 Token → 登录终端 → 获取目标 ID → 发送消息 → 接收 Webhook → 执行业务逻辑

接入完成检查

所有请求均使用 wechat-token Header；

已持久化保存 appId 与 wxid 的对应关系；

调用业务接口前能够确认终端在线；

已同时处理 HTTP 状态与业务字段 ret、msg；

Webhook 能在规定时间内返回成功响应；

已使用 Appid + Data.NewMsgId 对消息进行去重；

Token、代理密码和业务密钥未写入前端或公开仓库。

使用提醒：请使用状态正常、已实名认证且有真实使用记录的微信账号。首次接入先完成小范围联调，确认登录、消息和回调均稳定后，再逐步接入正式业务。

平台能力#

接入前准备#

推荐接入路径#

1. 获取 wechat-token#

2. 登录微信并保存 appId#

3. 验证终端是否在线#

4. 发送第一条消息#

5. 配置 Webhook#

最小闭环#

接入完成检查#