企业微信API接口二次开发：客户群 Webhook 收消息与主动发怎么拆

做私域时，需求单上常写「客户群自动通知 / 关键词自动回」。研发一上手容易按内部群机器人思路去找官方推送入口。外部客户群没有同一套能力：群里能说话的，只能是已经在群里的企业成员账号。企业微信 API 接口二次开发要补的，是收发两条链路，不是再找一个官方机器人开关。

本文只讲私域客户群的收发拆分：怎么收稳、怎么发准、账怎么记清。

为什么必须拆成「收」和「发」

客户群自动化通常有两类触发：

1. 自动回：客户先说话，系统再回

2. 主动推：工单变更、报价通过、到货提醒，不依赖客户先开口

两者最终都可能落到「往某个群发一条文本」，但触发源、幂等键、失败语义完全不同。混成一个「机器人功能」，后面排障会变成猜谜。

可上线的主链路可以概括成一句话：

Webhook 收事件 → 入队 / 业务判断 → API 主动发到客户群

接收侧：先当消息网关

企微事件一般以 POST JSON 打到你的公网地址。工程上建议固定顺序：

1. 校验签名（确认来源可信）

2. 解析时保留 int64 精度（会话 ID、群 ID、用户 ID 不要经 JS Number）

3. 用事件 ID 做推送重试去重；用「实例 ID + 消息 ID」做业务去重

4. 落库或入可靠队列后，再返回 HTTP 2xx

耗时逻辑（查 CRM、调大模型、拼话术）一律放 Worker。回调线程里同步跑业务，超时后你会看到「偶发丢消息」，却很难复现。

还要记住一条范围规则：经接口发出的消息，通常不会再推送正文；客户端手动发的才会。测试接收时，用另一个账号在客户端发一句，比反复调发送接口更靠谱。

消息类型先只处理文本即可。群聊看会话类型与 roomId，单聊看收发双方用户 ID。已读回执类事件不要当成新咨询。

发送侧：会话 ID 填错等于业务失败

文本发送在多数企业微信 API 体系里都是标准 HTTP：请求头带调用凭证，body 指定实例与目标会话。示意如下（字段名以你实际对接的文档为准）：

{
  "appid": "we_xxx",
  "conversationId": 1688855874759204,
  "content": "您的工单已更新，详情见群内说明。"
}

私域里最典型的坑是：接口返回成功，群里却没人看见——因为目标填成了个人会话，而不是客户群会话。上线前用同一实例把「给自己发」「发到目标群」各跑通一次，把正确的会话 ID 固化进配置或映射表。

发送不要事件来了就直调。按实例串行、加间隔、带业务幂等键，比再包一层 HTTP Client 重要。主动推用「业务单号 + 状态版本」去重；自动回用「实例 + 消息唯一标识」去重。两套账本不要共用一把锁。

私域场景怎么挂，怎么先别挂

适合先挂：

• 工单 / 物流状态变更的主动推（状态合并后再发，避免刷流水）

• 客户群关键词自动回（默认沉默，命中才回）

• 入群欢迎（按「群 + 成员 + 日」幂等，延迟几秒发）

先别挂：

• 回调里同步调大模型

• 无过滤的「有字就回」

• 运营群发与客服应答抢同一无优先级通道

接口能力可以对照开放文档理解请求模型；例如.eyunz.地址就是「每能力一路径 + Webhook 收事件」这一类接法。选型不重要，收发边界重要。

上线前五条检查

1. 实例在线，且成员仍在目标客户群

2. 回调公网可达，签名校验与去重已上线

3. 决策日志能区分 reply / skip 及原因

4. 发送任务能回答：哪个实例、哪个会话、哪个业务单、当时响应是什么

5. 主动推与自动回的幂等互不覆盖

小结

企业微信 API 接口二次开发做私域客户群，起点是承认「收」和「发」是两条管道。Webhook 只做网关，发送走队列与幂等，工单通知和自动回才有地方挂。下一篇可以继续写：客户加好友、资料变更这类事件，怎么驱动私域 CRM 建档，而不是只停在会回消息。