Appearance
API 使用规范
本文用于上线前检查和线上问题排查。建议开发完成后逐项核对，尤其是登录稳定性、发送频率、Webhook 响应和媒体下载队列。
账号要求
未绑定银行卡、未实名认证或注册不满 3 个月的微信号属于高风险账号，不建议接入本服务。
使用边界
本文给出的是降低风险的工程规范，不是“绝对不掉线”或“绝对无封号”的承诺。请把登录、发送、下载等高风险动作放入队列和告警体系。
一、登录与掉线
首次登录 24 小时内可能掉线
新账号首次登录后，24 小时内可能出现一次首夜掉线。掉线后请传入原 wcId 重新登录，避免创建新的微信设备。
常见掉线原因
| 原因 | 表现 | 处理建议 |
|---|---|---|
| 异省登录 | 扫码城市与手机常用地不一致，容易快速掉线 | 使用本省平台线路、Aid 本地代理或自定义代理 |
| 设备冲突 | iPad 真机登录、手机端退出、换手机后异常 | 避免多终端同时操作同一微信 |
| 非安全环境 | 登录未满 48 小时就频繁调用敏感接口 | 在线 1-2 天后再做高频操作 |
未传 wcId | 掉线重登时创建了新设备 | 每次重新登录必须传原 wcId |
| 连续失败 | 多次登录失败后触发限制 | 暂停操作，次日上午 8 点后再重试 |
如何判断是否创建了多个设备
在手机微信中打开「设置 → 账号与安全 → 登录设备记录」。多次重新登录后，iPad 开头的设备应保持为同一个。如果出现多个 iPad 设备，说明重登时没有正确传入原 wcId。
二、消息发送
频率建议
| 场景 | 建议 |
|---|---|
| 单账号发送 | 每分钟约 40 条 |
| 不同用户切换 | 间隔 1 秒以上 |
| 不同群发送 | 随机间隔 2-5 秒 |
| 业务系统发送 | 必须进入队列，禁止并发直发 |
常见发送失败排查
| 排查项 | 说明 |
|---|---|
| 账号是否在线 | 调用 查询在线状态 |
| 参数是否正确 | 核对 wId、目标 wcId、消息内容和接口路径 |
| 频率是否过快 | 手机端可能提示“发送频率过快请稍后重试” |
| 是否需要重试 | 建议做 3 次重试，并加入随机延迟 |
| 是否并发发送 | 同一微信实例应使用队列串行发送 |
群消息部分成员看不到
同质化内容过多、营销特征明显或发送过快时，微信可能降低消息的有效到达。建议降低频率、增加内容差异，并避免短时间向大量群发送相同内容。
图片、视频、文件发送慢
平台需要先从 URL 下载资源，再转发给微信。如果资源服务器慢，发送也会变慢。建议先用稳定公网资源测试，再排查业务资源服务器。
批量发送相同素材
不要让每个微信重复上传同一个素材。推荐先获取素材 XML，再使用转发接口发送，减少上传成本和风控风险。
| 方案 | 步骤 | 适用版本 |
|---|---|---|
| 素材群 | 创建素材群 → 素材账号发送素材 → 接收回调获取 XML → 其他账号转发 | 业务版 |
| 转发链路 | 发送资源给另一个账号 → 通过回调获取 XML → 用转发接口发送 | 业务版 |
| CDN 上传 | 调用 CDN 上传接口 获取密钥 → 组装 XML 转发 | 私有化版 |
三、消息接收
Webhook 响应要求
| 要求 | 说明 |
|---|---|
| 公网可访问 | 回调地址必须能被平台访问 |
| 快速响应 | 建议 6 秒内返回，业务处理放入异步队列 |
| 幂等处理 | 回调可能重复推送，建议用 newMsgId 排重 |
| 只处理入站消息 | API 主动发送的消息不会产生回调 |
TIP
开发阶段没有公网服务器时，可先用 Webhook 本地联调 临时接收回调；上线前必须替换为稳定业务域名。
消息接收慢或收不到
| 排查项 | 说明 |
|---|---|
| 回调接口不通 | 用 Postman 或 curl 测试回调 URL |
| 接口阻塞 | 检查回调服务是否存在慢查询、死锁或同步耗时任务 |
| 账号离线 | 用发送接口或在线状态接口确认，不能只看手机顶部状态 |
| 消息降权 | 群过多、内容同质化时，微信可能降低推送到达 |
四、好友相关
| 操作 | 建议 |
|---|---|
| 添加好友 | 每天 15-25 人，每 2 小时不超过 8 人，每次添加加入随机延迟 |
| 同意好友 | 每天被动通过不超过 200 人，大量扫码添加有封号风险 |
| 搜索好友 | 每日 10-50 次，必须做间隔 |
WARNING
新登录微信建议在线 7 天后再调用添加好友、同意好友等敏感接口，否则可能返回权重过低或触发风控。
五、群聊相关
| 问题 | 说明 |
|---|---|
| 获取不到群内非好友微信号 | 微信新规则限制，无法查看非好友微信号 |
| 群列表不完整 | 接口只能获取保存到通讯录的群；未保存群可在有人发消息后通过回调识别并保存 |
| 创建群聊失败 | 新登录微信建议在线 3 天后再创建群聊 |
| 群二维码不可用 | 新登录微信建议在线 3 天后再获取群二维码 |
创建群聊建议每天 10-15 个，间隔 10 分钟以上。
六、朋友圈
| 接口类型 | 建议频率 | 每日上限 |
|---|---|---|
| 获取动态 | 最低间隔 5 秒/次 | 200 次 |
| 点赞 / 评论 | 随机间隔 3-10 秒/次 | 500 条 |
新登录微信建议在线 1 天后再发布朋友圈。若自己可见但别人不可见，通常与发送过多、关键词拦截或内容违规有关。
七、媒体下载
调用要求
- 必须设置下载队列。
- 每条消息下载间隔建议随机 3-10 秒。
- 同一条消息只下载一次。
- 视频等大文件建议异步下载并查询结果。
常见问题
| 问题 | 说明 |
|---|---|
| 频率过高 | 收到消息立刻下载是常见错误，必须排队 |
| 文件下载失败 | 文件回调可能有两条，通常选择第二条下载 |
| 图片下载失败 | 可能没有普清或高清资源，需尝试其他类型 |
DANGER
频繁下载可能导致掉线。如果下载耗时无法满足业务需求，建议使用多个微信实例分担下载任务。
八、账号与风控
wcId 显示规则
| 场景 | wcId 返回值 | aliasName | 说明 |
|---|---|---|---|
| 默认微信号 | wxid_6tn88z16x6ou12 | 空 | 未自定义微信号，仍有一次自定义机会 |
| 已自定义 | wxid_ylxtflcg0p8b22 | fangqing0827 | 有原始 wxid，后来自定义了微信号 |
| 注册时自定义 | qq526552198 | 空 | 注册时就用了自定义号，无法再改 |
| QQ 注册 | fangqing_hust | heiheizwx | QQ 注册后自定义了微信号 |
| 公众号 | gh_88b080670a71 | jueduixiao888 | 普通公众号以 gh_ 开头 |
敏感接口在线天数建议
| 接口 | 最低在线天数 | 限制来源 |
|---|---|---|
| 获取群二维码 | 3 天 | 官方限制 |
| 发送朋友圈 | 1 天 | 官方限制 |
| 创建群聊 | 3 天 | 平台限制 |
| 添加好友 | 7 天 | 平台限制 |
| 同意好友 | 7 天 | 平台限制 |
TIP
平台限制的接口如不考虑风控风险，可联系技术支持申请解除限制。
接口次数和流量
- 每日最高 20 万次接口调用。
- 每日最高 2GB 流量。
- 超出后会被视为异常调用，请检查代码质量、重试策略和队列逻辑。