企业微信外部群怎么管理

先拆清楚：外部群管理由哪五件事组成

「把外部群管起来」写进需求文档只有一行，落到系统里是五件彼此独立的事。它们的数据来源不同、失败形态不同、负责重试的角色也不同，混在一个模块里写，第一次出问题就分不清该找谁。

• 群档案：群名、公告、标签、成员数这类描述群本身的信息。它是一个会持续腐化的长期对象，不是一次写入就完事的记录。
• 成员关系：谁在哪个群里。这份数据只能以事件为准，不能以调用返回为准。
• 内容触达：按群或按人分层发送。它是一个有分片、有限速、有回执的批量作业，不是一个 for 循环。
• 群内应答：监听群消息，命中显式触发条件后回复。结构与单聊机器人一致，差别在来源判定与是否被点名。
• 节奏与配额：以上四件事共用同一份速率预算，需要有人统一分配，否则一次批量对账就能把当天的触达额度占掉。

其中「内容触达」还要再拆一层：批量单聊、批量群消息、批量改群公告在工程上是三件事，送达口径和失败语义都不同，站内讲群发接口怎么用的那篇专门算过这笔账，混进同一张报表数字永远对不上。

这五件里只有内容触达和群内应答的主语是「你去调接口」，其余三件的主语都是事件。分开的直接好处是出问题时你能立刻回答「这条数据是谁写的」。站内讲企微外部群开发怎么落地的那篇把建群作业、邀请记账、群档案对账三段拆得更细，本页只保留结论。

开工前要准备的四样东西

缺任何一样，后面的步骤都能跑通，但跑不长。

• 账号接入与实例托管。每个企业微信账号对应一个独立实例，调用时用实例标识决定这次由哪个号发出。这一层不理顺，后面收到的事件属于哪个号都说不清。
• 一个能公网访问、能在毫秒级返回 200 的回调服务。事件处理必须异步，接收端只负责校验来源与快速 ACK。
• 两张表：群档案表与成员关系表。前者允许被对账作业覆盖，后者只接受事件驱动的写入，业务代码一律不许直接改。
• 一个内部验证群和一个内部接收方。所有新流程先打到这里跑通，再放进真实客户群。

分步骤实施

下面六步按依赖顺序排，每一步都写清看什么、怎么判断成了。不要跳步，前三步是数据地基，跳过去之后写的应答和群发都建在沙上。

1. 1打通一次最小调用。用控制台 https://console.wecomapi.com 创建的密钥，向一个内部接收方发一条文本。判据不是手机上收到消息，而是响应体为 {"code":0,"msg":"success"}，并且你已经把响应头里的 x-request-id 记进了日志。
2. 2订阅群相关事件并落库。回调服务收到事件后先返回 200，再入队。判据是：在内部验证群里手动拉一个人进来，队列里应当出现对应的成员变更事件，成员关系表在几秒内多出一行。
3. 3把群档案建起来。以事件增量为主、低频全量对账为辅。判据是随便挑十个群，库里的群名与真实群名一致，且每条记录都带「最后确认时间」。
4. 4接群内应答，但默认沉默。触发面只保留显式点名、指令前缀、白名单词表三种，其余一律不回。判据是把它放进内部验证群闲聊十分钟，它一句话都不该说。
5. 5做分层触达作业。按群标签选出目标，切成几分钟能跑完的批次，每条投递项带业务唯一键。判据是把同一批任务整批重跑一次，接收方不应该收到第二条。
6. 6放量。从内部群到一个真实群，再到一批群，每一档观察至少一个自然日。判据是批次高峰期 x-ratelimit-remaining 仍有余量，而不是贴着下限走。

群维度的发送端点与字段以线上接口文档为准，下面这段只用来确认链路本身是通的。

curl -i -X POST https://manager.wecomapi.com/message/sendText \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "guid":    "7db8...",
    "toId":    "78813...",
    "content": "链路自检，请忽略"
  }'

# 响应体： { "code": 0, "msg": "success" }
# 响应头 x-request-id           排障时提供它即可定位这一次调用
# 响应头 x-ratelimit-remaining  放量时用它判断节奏是不是太密

架构与数据流：谁调谁、状态存哪、失败谁重试

这套系统里有两条方向相反的数据流，把它们分开画，责任划分就是顺的。

入站流：企业微信侧发生事件，回调到你的接收端，校验来源后立刻 ACK，入队，消费者写库。这条流上重试的责任在投递方和你的队列，接收端不做业务判断，所以它本身不该有失败可言。

出站流：业务或运营发起意图，落成一条作业，调度器按账号与速率取件，调 wecomapi 的发送接口，回执写回作业项。这条流上重试的责任在调度器，业务代码只负责把意图写进作业表，不许直接调发送接口。

• 群的生命周期状态放在群档案表上，只由事件与对账推进。
• 成员关系只由入群、退群事件写入；调用返回只能记「已发起邀请」这个事实，不能记成「已入群」。
• 作业项状态（待发、已发、失败、已放弃）放在作业表上，它是唯一的送达口径来源。运营问「发出去多少」，答案只能从这张表出，不能靠数日志。

两条流的交汇点只有一个，就是应答：群消息事件进来、命中触发条件后生成一条出站作业，而不是在事件消费者里直接调发送接口。理由很实际，直接调用会让应答绕过统一的速率分配，一个刷屏的群就能把这个账号的额度吃光，而且这种静默不报错。

// 示意逻辑。入站事件的字段名与群维度端点以线上接口文档为准
async function onGroupMessage(raw) {
  const e = normalize(raw);                    // { room, message, guid, text }
  if (!shouldSpeak(e)) return;                 // 点名 / 前缀 / 词表，命中才继续
  if (!(await dedupe.acquire(`${e.room}:${e.message}`))) return; // 同群多账号只留一个

  await jobs.enqueue({
    bizKey: `reply:${e.room}:${e.message}`,     // 幂等键，事件重投不会多发
    guid:   e.guid,
    payload: await route(e),
  });
}

// 出站唯一出口：限速、重试、回执都收敛在这里
async function dispatch(job) {
  const res = await fetch("https://manager.wecomapi.com/message/sendText", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      guid:    job.guid,
      toId:    job.toId,
      content: job.payload,
    }),
  });

  const requestId = res.headers.get("x-request-id");        // 写回作业项，排障靠它
  const left = res.headers.get("x-ratelimit-remaining");    // 余量吃紧就拉长批间隔
  const body = await res.json();                            // { code: 0, msg: "success" }

  return { ok: body.code === 0, requestId, left };
}

错误处理与排障

这一节的投入产出比最高，也最常被跳过。前提是别按错误码死记，按「该做什么」分类。站内讲接口报错怎么分类处理的那篇分了四类，这里直接用。

• 确定性失败：参数不对、对象不存在。重试没有意义，直接标失败并让它能被人看见，不要静默丢弃。
• 状态失败：账号或群此刻不可用。过一会儿可能自行恢复，适合退避重试，但要有次数上限和放弃后的告警。
• 容量失败：命中频控。唯一正确的反应是降速，不是加线程；而且降速要比提速激进得多。
• 结果未知：超时、连接断开。这是最贵的一类，你不知道对方收到没有。只有投递项带了业务唯一键、发送侧做了去重，才敢重试，否则宁可标成待人工确认。

把「结果未知」判成确定性失败，结果是漏发；判成可以随便重试，结果是客户收到两条一样的内容。后者的投诉成本更高。

1. 1先分清是没发出去，还是发出去了没到。作业项的状态和它有没有 requestId，这两个字段就能把两种情况分开。
2. 2作业根本没生成，说明问题在入站流或规则上，不在发送。去看事件有没有进队列。
3. 3作业生成了但一直没被取件，看调度器的速率分配，常见原因是另一个批量任务把这个账号占满了。
4. 4调用发出去但返回非 0，按上面四类归好类再决定动作，不要一律重试。
5. 5一切正常但群里就是没动静，检查触发面与去重键。同一个外部群里常有你们的多个账号，另一个账号可能已经抢先应答，或者抢走了去重锁。

怎么判断真的做对了

「上线了」不是判据。下面几条都可观察，任何一条不成立，就说明还有一段没接上。

• 抽查十个群，库里的群名、成员数与真实情况一致，且每条记录都能说出最后确认时间是什么时候。
• 把昨天的群发作业整批重跑一次，作业表里的成功条数不变，接收方没有收到第二条。
• 拿任意一条已送达的消息，能在半分钟内从业务侧反查到它的 x-request-id。
• 在内部验证群里连着闲聊十分钟，机器人保持沉默；点它一次名，它在约定时限内回一次，不多不少。
• 批量作业跑到高峰时 x-ratelimit-remaining 仍有余量；如果它经常贴近下限，说明批次间隔该拉长了。
• 运营问「这次发了多少、送达多少、失败多少」，你能从一张表里直接答，不需要临时去数日志。