「微信机器人接口」这几个字太大，容易把登录、群发、加好友全塞进一个需求里。真正对接时，应该按能力拆。这篇教程只覆盖客服和私域最常用的三块：发消息、群相关、通讯录，并给出调用顺序和避坑点。

对接前先画一张能力边界

建议把接口分成“能日常用”和“要谨慎用”两类。

日常用（客服刚需）

• 发文本 / 图片 / 文件

• 收消息回调

• 获取好友信息

• 获取群成员

• 查询在线状态

谨慎用（有业务必要再开）

• 拉人进群

• 批量建群

• 自动通过好友

• 修改备注 / 打标签后马上群发

接口有，不等于运营策略允许。个人号二次开发尤其如此。教程里会写怎么调，但上线策略要单独评审。

发消息接口：先做对，再做全

调用原则

1. 接收人用稳定 ID，不用昵称

2. 文本、图片、文件分开的接口或明确的 type

3. 每次调用带 requestId

4. 发送结果要回写：成功、失败原因、微信侧返回

推荐发送顺序

新项目不要一上来就做图文混排。顺序如下：

1. 私聊文本

2. 私聊图片

3. 群文本（默认不 @）

4. 群 @ 指定成员

5. 文件

私聊文本不稳定，后面都不要做。很多“接口不行”的结论，其实是实例掉线或回调没配，跟发送能力无关。

发消息的三个保护

• 会话级间隔：对同一人连续回复，留 1–2 秒

• 失败分类：参数错误不重试，网络超时才重试

• 人工优先：会话标记为人工后，发送接口对机器人侧拒绝

这是接口层就能做的保护，不要等运营出了问题再补。

群相关接口：先读后写

群能力建议按这个顺序开放：

只读

• 群列表

• 群成员列表

• 群名称 / 群主信息

写入

• 发群消息

• 邀请入群

• 移出群成员（权限不够会失败，要能识别）

客服场景里，读接口的价值往往大于写接口。例如：

• 判断消息来自哪个群

• 判断发言人是不是群成员

• 把群和项目/门店做映射

“拉群”如果只是为了把客户扔进一个大群，先停一下。个人号拉群失败率、投诉率和客服体验，通常比接口文档看起来更差。

如果确实要做邀请入群，至少满足：

• 对方已是好友

• 有明确同意（表单/对话确认）

• 有频控

• 失败后转人工，不自动连试 10 次

通讯录接口：映射比列表更重要

通讯录不是把好友全量拉下来展示这么简单。你真正要的是映射：

微信好友标识 ↔ 你们系统里的客户 ID

没有这层映射，后面这些都会错：

• 自动回复发给重名的人

• 订单通知发到前任客户

• 群成员和 CRM 对不上

对接建议：

1. 首次全量同步一次好友（量小才全量，量大要分页）

2. 之后靠回调增量更新：新增好友、删除、改备注

3. 以微信稳定 ID 为主键，备注、昵称当辅助展示

不要用备注当主键。备注会被客服随手改。

一个合理的对接排期

第 1 天：登录 + 在线状态 + 发私聊文本
第 2 天：消息回调 + msgid 去重
第 3 天：通讯录映射
第 4 天：群消息接收与发送
第 5 天：图片/文件和失败监控

这个排期看起来慢，但比“两天接完所有接口，第三天全线错乱”快。

字段和示例去哪看

发消息的参数、群 ID 格式、好友列表分页，这些不要靠猜。个人号 RPA 方案里，GeWe API 把这些能力拆成接口模块，对接时按“消息 / 群 / 通讯录”分别查即可。文档地址：GeWe API - GeWe API｜微信 API 开发文档

业务代码里建议再包一层自己的 SDK 或 Gateway，不要每个 PHP 文件直接散落调用。后面换环境、加签、加日志都方便。

小结

微信机器人接口要对的不是“所有微信功能”，而是发消息、群信息、通讯录这三条能支撑客服闭环的能力。先读后写，先私聊后群，先映射后自动化。个人号二次开发用 GeWe API 这类 HTTP 接口，可以把对接变成普通的后端任务：看文档、对字段、补日志。接口接完只是开始，真正决定效果的是你怎么限制它、怎么转人工。