用开源项目 wecomapi 给企业微信外部群编程建群（实测记录）

最近在 GitHub 上翻到一个开源项目 wecomapi，专门做企业微信这块，正好解决了我一直手动做的痛点。做私域、SCRM 的时候老遇到同一个卡点：客户群得靠人一个一个手动拉，几十上百个群根本没法跟自己的业务系统打通。我一直以为「建群」这步只能在手机上点，翻了翻这个项目的接口才发现，外部群（客户群）的建群能力是可以编程调用的，建完还能拿到群 ID，后续改名、发公告、拉人全都接得上。照着 README 跑通之后，我把「怎么用 API 把一个外部群建起来」这件事记一下。

建群接口长什么样

项目里外部群相关的能力都归在 /room/* 这一组，建群用的是 /room/createRoom。我翻了下，核心参数其实只有两个：用哪个企业微信账号去建（guid），以及初始拉进群的成员列表（memberList，填客户的 userId）。

它的设计是所有外部群接口都走同一个入口 POST /api/qw/doApi，靠请求体里的 method 区分业务，鉴权 token 放在请求头里。我自己部署后试的请求长这样：

curl -X POST <网关地址>/api/qw/doApi \
  -H "<鉴权Token头>: <Token>" \
  -d '{
        "method": "/room/createRoom",
        "params": {
          "guid": "<账号实例ID>",
          "memberList": ["wmUserId_A", "wmUserId_B", "wmUserId_C"]
        }
      }'

这里有个细节我一开始没注意，踩了一下：建群至少得凑够初始成员。如果你的成员列表是从 CRM 里捞出来的客户线索，记得先用联系人侧的能力（/contact/*）确认这些 userId 是当前账号能触达的外部联系人，否则拉不进来。

群建好之后

实测下来，建群是个会产生「群事件」的动作，所以结果往往不是同步返回一个完整群详情，而是通过 Webhook 回调通知你。配好回调地址后，新建群会以系统事件的形式推过来，我抓到的结构大致是这样：

{
  "code": 0,
  "data": [
    { "guid": "<账号实例ID>", "cmd": 15500, "fromRoomId": "<新群的群ID>" }
  ]
}

cmd=15500 是系统事件这一类（群成员进出、群改名、新建群、解散都走它）；fromRoomId 就是新群的群 ID。我的做法是把它存进库，后面所有针对这个群的操作（改群名 /room/modifyRoomName、发公告 /room/modifyRoomNotice、拉人 /room/inviteRoomMember）都靠它定位。

处理回调有两条我反复验证过的铁律：3 秒内必须回 200，否则会被判超时重推；同一条事件可能推多次，要按 seq 做幂等去重，别因为重复推送把同一个群建两遍或记两条。

拿到群 ID 就能发消息

群 ID 到手后，我试了下给这个外部群发消息，和给个人发消息是同一套接口，只是把 toId 填成群 ID：

curl -X POST <网关地址>/api/qw/doApi -H "<鉴权Token头>: <Token>" \
  -d '{"method":"/msg/sendText","params":{"guid":"<账号实例ID>","toId":"<新群的群ID>","content":"欢迎进群，有问题随时找我"}}'

小结

用这个开源项目 wecomapi 建外部群，关键是把「主动调用建群」和「回调拿群 ID」这两步串起来：/room/createRoom 发起，cmd=15500 回调落库群 ID，之后改名、公告、拉人、发消息都顺着群 ID 走。多账号场景下每个企业微信账号一个 guid 独立调度即可。建群、拉群属于敏感操作，我跑的时候频率压得比较低，注意平台风控；相关能力仅用于客户服务、社群运营等正当场景，具体字段以官方接口文档为准。项目开源在 GitHub：github.com/wechat-ipad-api/wecomapi，感兴趣可以自己翻翻接口。

关键词：企业微信外部群、外部群API建群、createRoom、企业微信API、客户群运营、群事件回调、企业微信SCRM