企业微信群 API 能做什么

先搞清楚你是以谁的身份看这个群

需求方脑子里的模型通常是「后台管理所有群」：一个列表列出企业里全部外部群，点进去能改群名、能踢人、能发消息。这个模型是错的，而且错得很彻底，它会让整个排期从第一天就跑偏。

真实的模型是席位视角：程序通过一个账号接进来，这个账号在哪些群里，你就能看到哪些群；它在群里是群主还是普通成员，决定了它能做什么。同一个企业的两个账号，看到的群集合可能完全不重叠。网关式接入下这一点尤其直白 —— 一个账号实例就是一个视角，接几个号就有几个视角，没有第三种可能。

• 群的可见性是账号的属性，不是企业的属性。群档案表里的账号维度是主键的一部分，不是附加信息。
• 「企业里一共有多少外部群」这个数你算不出准确值，只能算「我接入的账号覆盖到的群」。报表口径要把这句话写上，否则老板问起来永远对不上。
• 加一个账号不等于多一批权限，等于多一个视角。要覆盖更多群，靠的是把维护这些群的账号接进来。

这条前提决定了后面所有事：能力清单是按「这个账号在这个群里能做什么」列的，不是按「系统能做什么」列的。企业微信群开发的排期十有八九就毁在这个差别上 —— 分不清这两句话，评审会上会一直在讨论一个不存在的产品。

群维度能力，按四类记

与其背接口目录，不如记四类。每一类的变化频率、成本结构和可靠性都不一样，混着用就会在错误的地方花力气。

• 身份类，这个群和谁有关：群的基本信息、群主是谁、由哪个账号在维护。低频变化，适合缓存，是其他三类的定位基础。
• 结构类，谁在群里：成员进出、邀请、群内管理动作。写操作受速率与容量约束，读出来的成员名单是快照，第二天就会腐化。
• 内容类，群里说了什么：群内消息收发。量最大、时效性最强，也是唯一一类发出去就撤不干净的动作。
• 事件类，发生了什么：入群退群、群信息变更、群内消息。它是唯一给你「变化」的一类，前三类的读接口只能给你「现在」。

四类摆在一起，有个规律就浮出来了：每一类里，写是意图、读是快照、事件才是事实。发起一次邀请只表示你想让某人进群，读一次成员列表只表示那一刻的样子，只有入群事件才证明这个人真的进来了。这个三分法能省掉后面一堆争论 —— 任何时候有人问「以哪个数据为准」，答案都是事件。

落到做法上：用 wecomapi 的群事件订阅拿到入群、退群与群信息变更，本地群档案由事件驱动更新；读接口只在两个场合出现，冷启动时拉一次底，以及低频对账时补差异。反过来，靠定时读接口维持群状态的系统，群数量一上来会同时被数据延迟和调用量夹住，那时候再改就是重构而不是优化了。

六件群 API 做不了的事，以及替代方案

1. 1把某个群的成员整体加成客户。群成员和客户是两个集合，出现在同一个群里不等于建立了可直接触达的关系。替代路径是群内引导，由本人发起或明确同意后再走添加流程 —— 转化率通常还更高，也不会把账号置于高风险的操作节奏里。
2. 2按群标识查任意一个群。你只能看到接入账号所在的群。需求里出现「按群 ID 查」时先确认这个 ID 从哪来，如果它不属于你接入的任何账号的视野，这条需求本身就不成立，不是排期问题。
3. 3拿到接入之前的群历史消息。群内容以事件流的形式产生，接入时间点之前发生的事不在你的数据里。这条影响的是排期不是设计：想做群会话分析，接入越早数据越完整。
4. 4按人统计群消息已读。群消息没有可依赖的逐人已读语义。替代指标是互动 —— 回复条数、被点名后的响应率、带参链接的点击人数。用互动做代理指标，比追一个拿不到的已读数实在得多。
5. 5静默把成员踢出群或者解散群。破坏性动作在群里是有社交后果的，而且它以某个账号的身份发生，群里所有人都看得见是谁做的。工程上的替代是归档：在自己系统里把群标为停止运营，停掉群发和机器人，不去动群本身。
6. 6让一个不在群里的账号往群里发消息。这是多账号方案里最常见的一类 bug：调度器把一条群消息派给了不在这个群的账号，然后收到一个看不懂的失败。它应该在派发前被本地挡掉，而不是靠接口报错来发现。

这六条的共同点是：它们都不是「接口没做」，而是席位视角这个前提的必然推论。理解了前提，就不必逐条去问「这个能不能做」，自己就能推出来 —— 这比抱着一份能力清单逐项核对高效得多，也不会因为清单更新而失效。

派发之前先做本地校验

从上面六条能推出一个通用做法：所有群操作在真正发出之前，先在本地校验一个三元组 —— 以谁的身份、对哪个群、做什么动作。

把校验放在本地而不是靠接口报错，有两个理由。一是省调用量，被本地挡掉的请求不消耗任何配额；二是失败原因清晰，「这个账号不在这个群里」比一个通用失败码好排查十倍，而后者在多账号场景下几乎必然出现。

// 示意逻辑，动作清单与实际可执行条件以 wecomapi 文档为准
const ALLOWED = {
  sendGroupMsg: (ctx) => ctx.inGroup,                  // 在群里就能发
  inviteMember: (ctx) => ctx.inGroup && ctx.canInvite, // 还要有邀请能力
  updateNotice: (ctx) => ctx.isOwner,                  // 群主身份才有意义
  removeMember: () => false,                           // 显式关掉，改走本地归档
};

async function dispatch(action, accountId, groupId, payload) {
  // 读本地群档案，不要每次现查 —— 档案由群事件驱动更新
  const ctx = await groupProfile.load(accountId, groupId);
  if (!ctx) throw new Error("account_not_in_group");   // 派发器选错号，本地就该拦住
  const gate = ALLOWED[action];
  if (!gate || !gate(ctx)) throw new Error(`action_not_allowed:${action}`);
  return execute(action, { accountId, groupId, ...payload });
}

这张表最大的价值不是拦截，是它把「我们到底允许程序对群做哪些事」写成了代码，而不是留在某次会议的记忆里。新需求进来先问一句它进不进这张表，比事后在代码里找散落的判断省事得多。

接入时间点就是你的数据起点

上一节第三条值得单独展开，因为它是六条里唯一一个「今天不做以后补不回来」的问题。

四类数据的可补性完全不同：身份类可以事后补齐，现在读一次就有了；结构类只能补到「现在有谁」，补不到谁什么时候进来的、谁中途退过；内容类完全补不了。也就是说，你今天不接，损失的不是今天的数据，是未来任何一次回溯分析的地基。

所以冷启动的第一件事不是写业务，是把事件通道接上并原样持久化。具体到做法上就一步：把群事件订阅打开，写一个只做落库和幂等的消费者。wecomapi 的事件回调是统一结构，这个消费者不需要按事件类型分支，先照原样存下来，解析等业务需求明确了再从这张表回放。

这一步做与不做，差别在半年后。那时候要做群活跃度分析，有原始事件表的团队跑一次回放就出结果，没有的只能从当天开始重新攒 —— 而这类需求提出来的时候，通常都是急的。

选型时怎么验群能力

评估企业微信外部群接口时别数能力清单有多少条，看三件事，每件都能在预发环境里半天验完。

1. 1事件类覆盖是否完整。入群、退群、群信息变更、群内消息，缺任何一类都意味着你要回去用轮询补，而轮询的成本随群数量线性上涨，这笔账在群数过千之后会非常明显。
2. 2群档案里有没有账号维度。没有这一列的方案，多账号一上来就要改数据模型，而那时候你已经有存量数据要迁。
3. 3失败原因能不能区分「账号不在群里」「没有相应能力」「频控」。这三类的正确处理方式分别是修派发逻辑、改需求、退避重试，混成一个失败码，重试逻辑就没法写对。