企业微信如何自动拉群/建群

先拆开：自动拉群其实是四件事

搜「企业微信如何自动拉群」的人，脑子里通常是一个动作：点一下，群建好、人进来。落到系统里它是四件独立的事，每一件的失败方式都不一样。混在一个函数里写，第一次批量跑就会分不清是哪一步出的问题。

1. 1建群：按主题、区域或活动规则创建群并拿到群标识。这是一次写操作，返回成功只代表请求被受理。
2. 2邀请：向目标客户发起入群邀请。同样是意图不是结果 —— 对方可能没点开、可能已过期。
3. 3确认：监听入群事件。只有事件到达才说明这个人真的进来了，成员关系一律以事件为准。
4. 4跟进：入群后发欢迎语与群规、按来源打标签，把人导进对应的运营序列。

站内讲外部群开发怎么落地的那篇把这四段的工程判断展开得更细：建群作业的幂等键怎么从业务数据里重算、邀请表和成员表为什么必须分成两张。这一页只给总纲，记住一句话就够：写是意图，读是快照，事件才是事实。

动手之前要备齐的东西

• 一个已接入且在线的账号实例。群的可见性是账号的属性 —— 这个账号在哪些群里，程序才看得到哪些群，不存在「一个后台看到企业全部外部群」这回事。
• 在控制台创建好的密钥，调用时以 Authorization: Bearer 的形式带上；请求体与响应体都是 JSON。
• 一个公网可达的回调地址，用来接收入群一类的事件。没有它，第三步「确认」就无从谈起，只能退回定时读成员列表，群一多会同时被数据延迟和调用量夹住。
• 一张群档案表和一张成员表，主键里要带账号维度，否则多号接入后同一个群会串。
• 一个能限速、能重试、能记录每次调用的任务队列。批量建群与批量邀请都不该同步跑在业务请求里。

分步实施：每一步看什么、怎么算成了

1. 1定义分群规则，生成待建群清单。把「按什么维度分群」写成可重算的规则，例如活动标识加批次号加序号。看什么：每一行都要能算出一个稳定的幂等键。算成了：同样的输入重跑一次，清单逐行一致，不多出行。
2. 2异步建群。清单丢进队列，由作业去调建群接口，业务侧只拿到作业标识。看什么：响应体的 code 是否为 0，响应头 x-request-id 要连同作业一起落库。算成了：群档案表出现记录，状态为 creating。
3. 3等群真正可用再往下走。给群维护状态机：creating 到 created 再到 ready。建群返回成功与群可被邀请之间存在时间差，紧接着拉人有一定概率打空。算成了：状态推进到 ready，且由可用性确认或第一个群事件驱动，不是代码里 sleep 几秒。
4. 4分批发起邀请。按账号维度限速，把邀请摊到多个时段，批与批之间留间隔。看什么：响应头 x-ratelimit-remaining，下降过快说明节奏该放慢。算成了：邀请表写入一条「已发起」，此时不要碰成员表。
5. 5用事件确认入群。回调服务收到事件先快速返回 200，再入队异步处理。看什么：事件里的群与成员标识能否对上库里的群档案。算成了：成员表出现这条成员关系，邀请表对应记录被标记为已转化。
6. 6入群跟进。发送欢迎语与群规，按来源给成员打标签。看什么：发送结果与打标签结果分别记账，不要合并成一个布尔值。算成了：这条成员既有标签，也有一条带 x-request-id 的成功发送记录。

# 建群与邀请的路径、字段以线上接口文档为准
curl -i -X POST https://manager.wecomapi.com/message/sendText \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "guid":    "7db8...",
    "toId":    "R_1042",
    "content": "欢迎加入，群内答疑时间为工作日 10:00-18:00。"
  }'

# 响应体：{ "code": 0, "msg": "success" }
# 加 -i 才能拿到这两个响应头：x-request-id 落库备查，
# x-ratelimit-remaining 用来提前降速。toId 取值格式以线上接口文档为准。

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

职责摆清楚，出事时才知道该看哪一侧。这条链路上有四个角色，各写各的数据，不互相代笔。

• 调度侧：由定时任务或业务事件触发，负责生成清单、限速、排队。它只发起动作，不记录结果。
• 接口侧：wecomapi 承担账号接入与协议细节，REST 风格、统一鉴权、按幂等语义设计，网络抖动后重试是安全的。
• 回调侧：接收事件，验签后先快速 ACK 再入队。链路上的「事实」全部由这一侧写入。
• 存储侧：群档案表存状态机，邀请表存意图，成员表存事实。三张表不要合并，合并之后就分不清一条成员关系是猜出来的还是收到事件写的。

// 入群事件到达后，才写成员关系并发欢迎语。
// 事件名、载荷字段名，以及 toId 接收群标识时的取值格式，
// 一律以线上接口文档为准 —— 下面的 evt 只是占位，不要照抄字段名。
onGroupEvent(async (evt) => {
  // toMemberRow 是你自己的映射函数：把事件载荷转成你的表结构
  const row = toMemberRow(evt, "campaign_618");
  await db.members.upsert(row);

  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,
      toId: row.targetId,
      content: welcome,
    }),
  });

  const { code } = await res.json();
  if (code !== 0) {
    // 排障时把这个交给我们即可定位单次调用
    logger.warn({ requestId: res.headers.get("x-request-id") }, "welcome failed");
  }
});

重试责任只放一个地方：队列的消费者。调用方不要自己写 for 循环重试，回调处理失败也不要卡在请求生命周期里重试，统一进重试队列，多次失败落死信并保留原始报文。站内讲外部群常见限制的那篇把约束分成容量、速率、行为三类，速率类适合退避重试，行为类重试没有意义，只会让情况更糟。

错误处理与排障

拉群链路上的失败大致落在四处。先分清是哪一处再决定怎么处理 —— 大部分无效排查都源于拿速率问题的手段去解时序问题。

• 鉴权失败：密钥过期或没带上。特征是所有调用一起失败、与业务数据无关，先到控制台确认密钥状态与轮换记录。
• 被限速：失败集中在批量高峰，且失败前 x-ratelimit-remaining 已经很低。处理方式是退避和摊平，不是加大并发。
• 调用成功但结果没发生：建群返回 code 为 0 群却迟迟不可用，邀请发出去入群事件一直不来。这类最容易被当成 bug，多数其实是时序问题 —— 拿调用返回当结果记账就会这样。
• 事件没到：回调地址不可达、验签失败被自己拒了、或者事件收下了但消费者挂了。看回调服务的接入日志分辨：一条请求都没有是网络或配置问题，有请求但都被拒是验签问题，收下了库里却没数据是消费者问题。

1. 1先取 x-request-id。每次调用都把这个响应头落库，排障时给出它就能定位到具体某一次调用，比「昨天下午有几个群没建成」有用得多。
2. 2判断是不是孤例。同批里其他调用成功，多半是数据或时序问题；整批一起失败，先查鉴权与网络。
3. 3换一个账号实例重放同样的操作。仍然失败说明与账号无关；只在原来那个号上失败，就去看它的在线状态与近期操作密度。
4. 4最后才改代码。前三步没定位到根因就动手，通常结果是给一个时序问题加了 sleep。

怎么验证做对了

「跑通了」不是可验收的说法。下面五条都能直接查，建议在放量前逐条过一遍。

• 幂等：用同一个幂等键把建群作业重跑三次，群档案表里只应有一条记录，不多出空群。
• 时序：随机抽十个群，检查它们进入 ready 的时刻是否都早于该群第一条邀请的发出时刻。
• 来源分离：抽查一个「已邀请未入群」的客户，他应当在邀请表里、不在成员表里。两张表如果对得严丝合缝，说明成员关系是用调用返回写的，不是事件写的。
• 可追溯：任挑一条欢迎语发送记录，能凭库里存的 x-request-id 说清它是哪一次调用。
• 对账：跑一次冷读，把接口读到的成员名单与库里的成员表比对，差异率应稳定在很低的水平且不随时间单调上升。单调上升说明有事件在丢。

五条都过了再谈放量，节奏上分批、分时、分号，先用小流量测邀请文案与入群转化。群建起来之后怎么长期运营是另一件事：站内讲社群运营系统化的那篇强调群要有生命周期、尤其要有退役，讲客户群机器人的那篇写了入群欢迎的时序坑和同群多账号重复回复怎么去重，接着往下读比在这一页展开更合适。