★ FEATURED ARTICLE 做企业微信私域的系统最容易被低估的一块就是外部群消息推送。很多人接到需求的第一反应是拉个群机器人 webhook往群里 POST 一条 JSON收工。真上手才发现外部群根本加不了群机器人接口调通了消息也发不出去日志里全是 errcode成员那边还收不到任何提示。我前后在三四个项目里踩过这套流程的坑从早期的“硬发”到后来的“任务下发 催办 结果回收”方案改了不止一版。这篇就把企业微信外部群消息推送这件事从底层逻辑、通道选型、接口实操到排查经验完整拆一遍。不管你是刚接需求的后端还是被业务追着问“为什么消息没发出去”的产品或运营看完至少能少走两三个星期的弯路。1. 先搞清楚“外部群”到底是什么别一上来就写代码外部群这三个字听起来简单实际在企业微信的体系里有非常明确的边界。它指的是群成员里含有外部联系人也就是不在本企业通讯录里的人的群典型形态是“企业成员 客户”的客户群。这类群在数据模型上归属于“客户联系”模块而不是普通的内部会话。这个归属关系决定了它能用哪些接口、走哪些权限、受哪些配额限制。我见过最常见的误判是把内部群的经验直接搬到外部群上内部群能加机器人就以为外部群也能内部群能用应用消息推到群里就以为外部群也行。结果代码写完联调接口返回一个权限错误或者干脆消息石沉大海。所以在动手之前先把通道矩阵搞清楚比写一百行代码都值。1.1 外部群和内部群的三条硬边界第一条边界是成员构成。内部群的成员全部来自企业通讯录群主和管理员对群有完全的控制权外部群的成员包含外部联系人群主虽然是企业成员但对群内外部人员的行为没有管理权群本身也不进入企业的“群管理”体系。这条差异直接导致很多内部群的管理接口在外部群上不可用。第二条边界是数据归属。外部群的数据挂在“客户联系”下面通过externalcontact系列接口访问需要单独开通客户联系权限并且调用身份必须是配置了客户联系功能的成员。而内部群走的是会话相关的接口两套权限体系互相独立一个应用的 secret 不一定能调另一个模块的接口。第三条边界是发送控制权。这是最关键的一条。内部群消息可以由系统直接投递发出去就发出去了外部群消息在企业微信的产品设计里最终发送动作必须由企业成员在客户端确认。也就是说系统能做的是“把消息准备好、把任务派下去”真正点“发送”的是人。这不是接口没开放而是产品层面的约束目的是防止企业绕过成员直接骚扰客户。注意如果你的需求文档里写着“系统自动往客户群推送消息无需人工干预”这个需求在当前的企业微信能力下是不成立的需要在需求评审阶段就把它掰回来否则后面全是无效开发。1.2 四条通道的适用性对照把市面上常被问到的几种推送方式拉一张表能省掉大量试错时间。这张表是我自己项目里总结的具体权限以官方最新文档为准。通道能否直达外部群是否需要成员确认主要限制群机器人 webhook否无只能在内部群添加外部群没有添加入口应用消息agent message否否接收方只能是企业成员无法投递到群会话客户群群发任务下发是是每天每个客户群有条数上限任务需成员确认会话内容存档否无只读能力用于合规留痕不能主动发客服消息否否一对一场景与群消息无关从表里能看出来真正能触达外部群的只有“客户群群发”这一条官方路径。其他的要么根本进不去要么只能读不能写。有些团队会想歪招比如用成员的账号模拟客户端操作这种方案不但违规账号被封的风险也极高属于典型的“技术上能跑通、业务上不能用”。1.3 为什么外部群没有机器人这条路群机器人本质上是一个挂在群会话上的 webhook 地址任何持有地址的人都能往群里发消息。这个模型在内部群是安全的因为群成员都是企业可控的人。但外部群里坐着客户如果允许一个公开的 webhook 往群里推消息等于给企业开了一个可以无限骚扰客户的通道风险不可控。所以产品侧直接把这条路封死了只留“成员确认”这一种模式。理解了这个设计意图后面所有的方案设计就顺了系统不是“发送者”而是“任务调度者”不追求“发出去”而是追求“让该发的人准时、准确地发出去并且知道发没发”。这个定位转变是整个方案的地基。2. 整体方案设计把“推送”拆成任务调度问题定位清楚了架构就好画了。我不建议一上来就写调用接口的代码先把系统要承担的职责列清楚维护外部群和群主的映射关系、按业务规则生成待发内容、把任务派给正确的群主、催办没确认的人、回收发送结果、处理失败重试。这六件事构成了一个完整的闭环缺一件线上就会出问题。2.1 为什么把“客户群群发”定为主通道选型这件事没什么悬念因为在外部群这个场景里官方只给了这一条合规路径。但值得说清楚的是它的能力边界避免业务方产生不切实际的期待。这个接口的调用模型是你指定一个sender企业成员通常是群主提交一份消息内容企业微信会在这位成员的客户端里生成一条“待发送”的群发任务。成员打开客户端选择要发送的客户群点确认消息才真正落到群里。接口本身不接收具体的群 ID 列表你没法精确指定“发到 A 群不发到 B 群”。这个设计会带来一个很实际的问题如果某个群主名下有 20 个客户群但这次只想发其中 3 个系统层面是控制不了的只能靠任务描述里写清楚“请发送至 XX 活动群”靠人去执行。我当时的做法是在任务文案里带上群名关键词并且在培训文档里明确操作规范实际执行下来准确率能到 95% 以上剩下 5% 靠事后核对补。2.2 系统分层与数据流我习惯把整套系统分成四层每层职责单一出问题好定位。第一层是数据层存两张核心表群表chat_id、群名、群主 userid、群状态、成员数、最后同步时间和任务表任务 ID、msgid、sender、内容摘要、创建时间、状态、确认时间、失败原因。群表靠定时拉取加回调事件双保险维护任务表靠接口返回和结果查询接口更新。第二层是调度层负责按业务规则筛选目标群主、生成任务批次、控制发送节奏。这一层要把配额算清楚避免一窝蜂调接口把日限额打满。第三层是接口层封装 access_token 管理、请求重试、错误码翻译。所有对企业微信的调用都走这一层不允许多处散落。第四层是运营层包括催办、结果看板、失败清单。这层最容易被忽略但没有它任务发下去就成了黑盒业务方天天来问“到底发了没有”。数据流大致是业务系统触发 → 调度层筛选群主 → 接口层创建群发任务 → 返回 msgid 入库 → 定时催办 → 定时查询结果 → 更新任务状态 → 看板展示。2.3 关键配额先算清楚别等线上打满配额这件事必须提前算我吃过一次亏活动当天临时扩量接口调用直接触顶后面的任务全部失败补救都来不及。第一类配额是群维度的发送频次。每个客户群每天能接收的企业群发消息是有上限的这个上限比较紧具体数值官方文档里有明确说明不同时期可能有调整。这意味着同一个群一天内不能被多个业务线反复轰炸必须做全局的发送日历把多个业务方的需求合并排期。第二类配额是接口调用频次。客户联系相关接口有每日调用总量限制通常和企业规模挂钩。拉群列表、查群详情、创建任务、查询结果都算调用如果群数量多光同步一遍群列表就能吃掉不少额度。我的做法是把群列表同步频率降到每天一次增量靠回调事件补详情按需拉取并缓存。第三类配额是任务创建频率。创建群发任务的接口有独立的频率限制短时间内大量创建会被限流。所以要给调度层加一个令牌桶按每秒几个请求的节奏平滑发送遇到限流错误码就退避重试。举个实际的算法假设企业有 120 位成员担任群主名下共 860 个客户群。因为任务是按sender维度创建的所以一次全量群发需要创建 120 个任务而不是 860 个。如果接口限制是每秒 20 次120 个任务 6 秒就能发完压力不大但如果企业有 2000 位群主就需要 100 秒这时候必须做分批和断点续传防止中途失败后无法定位进度。3. 实操第一步鉴权、白名单与可信配置真正开始写代码第一件事不是调业务接口而是把 access_token 管好。这个环节看着简单实际上是线上故障的高发区。我见过不止一个项目因为 token 管理不当导致大面积接口失败。3.1 access_token 的正确拿法和缓存策略企业微信的 access_token 有有效期通常是两小时。每次调用业务接口都要带上它而获取 token 的接口本身也有频率限制。如果你在每个业务请求里都去换一次 token很快就会触发限流如果多个服务实例各自缓存又会互相把对方的 token 顶掉。正确的做法是集中缓存 提前刷新 单飞锁三件套。集中缓存指把 token 放在 Redis 这类共享存储里所有实例读同一份提前刷新指在过期前留出缓冲时间主动换新避免临界点大量请求同时失效单飞锁指同一时刻只允许一个实例去换 token其他实例等待结果。缓冲时间给多少合适我一般留 5 分钟。也就是说 token 有效期 7200 秒缓存 TTL 设 6900 秒。这样即使刷新失败还有 5 分钟的窗口做重试不会立刻中断服务。还有一个细节token 换新之后旧 token 通常会有一个短暂的共存期但不要依赖这个特性。如果你的系统里有长耗时的批量任务务必在每批开始前重新读一次缓存里的 token而不是在任务开始时取一次用到底。import time import redis import requests CACHE_KEY qywx:access_token LOCK_KEY qywx:access_token:lock def get_access_token(corpid, corpsecret, r: redis.Redis): cached r.get(CACHE_KEY) if cached: return cached.decode() # 简易单飞拿不到锁就短暂等待后重读缓存 if not r.set(LOCK_KEY, 1, nxTrue, ex10): for _ in range(20): time.sleep(0.3) cached r.get(CACHE_KEY) if cached: return cached.decode() raise RuntimeError(token 获取超时) try: resp requests.get( https://qyapi.weixin.qq.com/cgi-bin/gettoken, params{corpid: corpid, corpsecret: corpsecret}, timeout5, ) data resp.json() if data.get(errcode) ! 0: raise RuntimeError(fgettoken failed: {data}) token data[access_token] expires_in data.get(expires_in, 7200) # 提前 300 秒过期留出重试窗口 r.set(CACHE_KEY, token, exmax(expires_in - 300, 60)) return token finally: r.delete(LOCK_KEY)这段代码可以直接用但要注意corpsecret不要硬编码在代码里放配置中心或者环境变量。另外不同应用的 secret 是不同的客户联系模块要用对应的 secret用错了会返回权限类错误。3.2 可信 IP 和可信域名两个容易混淆的配置这两个概念经常被搞混但作用完全不同。可信 IP是限制哪些服务器可以调用你的应用接口。企业微信的部分接口会校验请求来源 IP如果服务器出口 IP 不在白名单里调用会直接失败报的是“不合法 IP”这类错误。配置入口在应用详情页里需要把服务器的公网出口 IP 填进去。这里有个坑如果你的服务部署在弹性 IP 或 NAT 网关后面出口 IP 可能会变一定要确认是固定 IP否则今天配好明天就失效。可信域名是网页授权和 JS-SDK 用的和消息推送没有直接关系。很多人在排查消息发不出去的时候跑去配可信域名配完发现毫无变化白折腾。要记住发消息靠的是接口调用权限和 IP 白名单不是域名。还有一个回调 URL用于接收群变更这类事件通知。它需要配置 URL、Token、EncodingAESKey 三样东西并且要在 5 秒内返回响应否则企业微信会重试。这个 URL 和消息发送也是两回事别混在一起。3.3 一个能直接用的请求封装所有接口调用我都建议统一走一个封装把 token 注入、超时、重试、错误码翻译都收在一起。下面这个封装用了重试装饰器的思路重点看错误处理逻辑。import requests def call_api(path, payloadNone, methodPOST, retry2): token get_access_token(CORPID, SECRET, redis_client) url fhttps://qyapi.weixin.qq.com/cgi-bin/{path} params {access_token: token} for attempt in range(retry 1): try: if method GET: resp requests.get(url, paramsparams, timeout8) else: resp requests.post(url, paramsparams, jsonpayload, timeout8) data resp.json() except requests.RequestException as e: if attempt retry: raise time.sleep(1 attempt) continue errcode data.get(errcode, 0) # token 类错误清缓存后重试一次 if errcode in (40014, 42001) and attempt retry: redis_client.delete(CACHE_KEY) token get_access_token(CORPID, SECRET, redis_client) params {access_token: token} continue # 限流类错误退避重试 if errcode 45009 and attempt retry: time.sleep(2 ** attempt) continue return data return data这段封装的关键点在于区分错误类型。token 失效要清缓存重取限流要退避等待业务错误比如群不存在重试没有意义直接抛给上层处理。如果不做区分所有错误都无脑重试会把配额浪费在注定失败的请求上。4. 实操第二步把外部群列表维护起来没有准确的群数据后面的任务派发就是瞎猜。群列表的维护要做到“准”和“全”靠的是主动拉取和被动回调两条腿走路。4.1 拉取客户群列表的分页处理群列表接口支持分页参数是offset和limit单页上限比较大。接口返回的是群 ID 和状态不含群名、群主这些明细明细要另外调群详情接口拿。这里有个性能上的取舍如果企业有几千个群每个群都调一次详情接口调用量会非常大很容易触发日限额。我的做法是分级缓存群 ID 列表每天全量同步一次群详情只对“本次任务涉及的群”按需拉取拉完缓存 24 小时群状态变化靠回调事件触发单群刷新。分页拉取时要注意offset是从 0 开始的返回条数小于limit就说明到底了。但不要只靠这个判断最好同时记录总数字段做交叉校验防止中间有数据变动导致漏页。def fetch_all_group_chats(): offset 0 limit 500 result [] while True: data call_api( externalcontact/groupchat/list, {offset: offset, limit: limit, status_filter: 0}, ) if data.get(errcode) ! 0: raise RuntimeError(data) batch data.get(group_chat_list, []) result.extend(batch) if len(batch) limit: break offset limit time.sleep(0.2) # 平滑请求避免触发限流 return resultstatus_filter这个参数很关键。客户群会因为群主离职、群解散等原因变化状态如果不加筛选会把已经失效的群也拉进来后面派任务必然失败。正常运营的群才纳入发送范围。4.2 群变更回调让数据自己找上门光靠定时同步数据永远有延迟最坏情况下可能延迟一整天。这时候需要回调事件来补。企业微信提供了客户群变更事件群创建、群更新、群解散、群转让都会推过来。接收回调有几个硬性要求URL 要能公网访问、要完成签名校验、要在 5 秒内返回。我的做法是收到事件后只做两件事——验签、丢进消息队列立刻返回成功。真正的业务处理放在异步消费者里做这样既保证了响应速度又避免了处理逻辑阻塞导致的重复推送。事件到达之后按变更类型分别处理群创建就补一条记录并拉详情群更新就刷新群名和成员数群解散就把状态置为失效并从后续任务的候选池里剔除群转让要特别小心因为群主变了后续的sender也要跟着改否则任务会派给一个已经不管这个群的人。提示群主变更是一个高频的线上问题源。我建议在任务创建前再做一次群主校验比对数据库里的群主和实时查到的群主是否一致不一致就先修数据再派任务。4.3 群数据表的字段设计表结构设计得好后面写查询会很轻松。我用的核心字段大致是这样字段类型说明chat_idvarchar群唯一标识以 wr 开头chat_namevarchar群名称需详情接口获取owner_useridvarchar当前群主的企业成员 IDmember_countint群成员数statustinyint0 正常1 失效last_sync_atdatetime最近一次同步时间sourcevarchar数据来源定时同步或回调索引我建在owner_userid和status上因为调度时最常用的查询是“找出某个群主名下所有正常状态的群”。chat_id建唯一索引防止回调重复推送导致数据重复。5. 实操第三步创建群发任务并落地到这一步才是真正的消息推送动作。前面所有的准备都是为了让这一步的调用尽量不出错。5.1 群发接口参数逐项拆解创建群发任务的接口是externalcontact/add_msg_template核心参数有这么几个每个都有讲究。sender是必填的指定由哪位成员来发送必须是配置了客户联系功能的成员并且要是目标群的群主。这里最常见的错误是传了一个不在客户联系范围内的成员接口直接报权限错误。所以派任务之前要先校验sender是否在可见范围内。chat_type决定是发给客户还是发给客户群外部群场景填group。填错了会走成一对一客户消息群里的客户根本收不到。allow_select控制成员能否自选发送对象。填 true成员可以只发部分群填 false就是把名下所有客户群全发一遍。这个参数一定要想清楚选错了要么发漏要么把不该发的群也覆盖了。我一般填 true配合任务说明里的操作指引把选择权交给成员。text.content是文本内容有长度上限太长的文案会被截断。如果要发图文用attachments数组里面可以放图片、链接、小程序、文件、视频这几种类型每种类型有自己的参数要求。图片需要先上传临时素材拿media_id或者直接给pic_url。接口返回里最重要的是msgid它是这条任务的主键后面的催办和结果查询都靠它。如果返回里带fail_list说明有一部分目标对象没派成功要单独处理。5.2 消息体形态与内容合规消息内容这块技术上简单业务上坑多。纯文本适合通知类内容图文适合活动推广小程序卡片适合引流。但不管哪种形态都要过两道关。第一道是技术关。图片素材有大小和格式限制链接的域名要能正常访问小程序卡片要填对 appid 和页面路径。这些参数错一个整条消息就发不出去而且错误码往往指向不明显排查起来费劲。第二道是内容关。外部群里的消息会直接触达客户内容必须符合规范不能有诱导分享、虚假承诺这类表述。我的建议是在系统里加一层内容审核把敏感词过滤和格式校验前置不让有问题的内容进入任务队列。这一层可以很简单一个词表加几条正则就够用。注意同一份内容不要原样反复推给同一批群。客户群的接收频次本来就有限重复内容会加速消耗额度也容易引起客户反感。系统里应该记录“某个群最近收到过哪条内容”做去重判断。5.3 发送结果回收的三种方式任务创建成功不等于发送成功中间还隔着“成员确认”这一关。结果回收我用了三种方式组合。第一种是主动查询。通过群发记录列表和成员执行结果接口按时间段拉取任务的执行情况更新到本地任务表。这种方式适合做定时对账比如每小时跑一次把状态为“待确认”的任务刷新一遍。第二种是催办接口。对于创建后长时间未确认的任务可以调用提醒接口给成员发通知把任务重新推到他的客户端首页。催办要控制频率一天一两次就够催太频繁成员会反感。第三种是人工兜底。再自动化的系统也会有人漏发所以要有运营看板把“超时未确认”的清单列出来让运营人员直接找人沟通。这种方式看着原始但在实际项目里最有效。5.4 完整的任务创建流程把上面这些串起来一个完整的任务创建函数大致是这样def create_group_task(sender, content, attachmentsNone, allow_selectTrue): payload { chat_type: group, sender: sender, allow_select: allow_select, text: {content: content}, } if attachments: payload[attachments] attachments data call_api(externalcontact/add_msg_template, payload) if data.get(errcode) ! 0: return {ok: False, errcode: data.get(errcode), errmsg: data.get(errmsg), sender: sender} return { ok: True, msgid: data.get(msgid), fail_list: data.get(fail_list, []), sender: sender, }调用方拿到 msgid 后立刻入库状态置为“待确认”。然后由定时任务负责催办和状态刷新。这里要注意fail_list里的成员是派发失败的要单独记一条失败记录分析原因不要和“已派发但未确认”混在一起。6. 稳定性设计限流、去重、重试与监控功能跑通只是第一步线上能不能稳住看的是这四件事做没做到位。6.1 限流要分三个维度做第一个维度是接口级限流。给每个接口配一个令牌桶比如创建任务每秒 10 次查询结果每秒 20 次。超过就排队等待而不是直接失败。第二个维度是群级频控。维护一张“群-日期-发送次数”的记录表同一群同一天超过阈值就跳过并记录跳过原因。这个逻辑要在调度层的最前面做越早拦截越省资源。第三个维度是成员级频控。同一位群主一天内被派太多任务体验会很差也容易漏发。我给每个群主设了一个每日任务上限超过就把任务顺延到第二天。6.2 幂等与去重重复派单是这套系统里最容易出的问题。业务系统重试、定时任务重跑、人工误操作都可能触发重复创建。防护手段有两层。一层是业务唯一键。给每个任务生成一个业务键比如“业务线 内容 ID 群主 日期”的哈希值入库时建唯一索引重复插入直接失败。另一层是入库前查重。创建任务之前先查一下当天有没有同内容、同群主的任务有就跳过。这层多一次查询但能挡掉大部分重复。6.3 失败重试要有边界不是所有失败都值得重试。我的分类是这样的网络超时、限流、token 失效这三类可以重试退避策略用指数递增最多三次参数错误、权限不足、群不存在这三类不重试直接标记失败并告警因为重试多少次结果都一样。重试还要防止雪崩。如果某个时间段大量任务失败说明可能是上游接口出问题这时候应该熔断暂停派单等恢复后再继续而不是拼命重试把配额耗尽。6.4 监控要有三个看板第一个是调用健康度看接口成功率、平均耗时、错误码分布。错误码分布特别有用某个错误码突然飙升基本能定位到具体原因。第二个是任务执行率看创建了多少任务、确认了多少、超时多少、失败多少。这个指标直接反映业务效果。第三个是配额消耗看每天的接口调用量、群发送次数接近上限要提前预警。我在项目里设置了几条告警线任务确认率低于 70% 报警接口错误率超过 5% 报警配额消耗超过 80% 报警。这三条线跑起来之后大部分问题都能在业务方发现之前处理掉。7. 常见问题与排查速查表最后这部分是我踩过的坑的集合按出现频率排序遇到问题可以直接对照。7.1 错误码速查错误码含义排查方向40001凭证无效secret 是否用错是否用了其他应用的 secret40013企业 ID 不合法corpid 是否填错是否用了测试企业的40014access_token 不合法缓存里的 token 是否已失效是否被其他实例顶掉42001token 已过期检查刷新逻辑缓存 TTL 是否设置过长45009接口调用超限查看当日调用量是否有死循环重试60020访问 IP 不在白名单检查服务器出口 IP是否为固定 IP301002无权限操作应用是否开通客户联系权限成员是否在可见范围40003用户标识不合法userid 是否正确是否已离职86003客户不存在客户是否已删除企业成员这张表建议直接贴到项目的故障排查文档里值班的人第一时间能对上。7.2 三个“不报错但发不出去”的隐形问题比错误码更麻烦的是接口返回成功但实际没效果。我遇到过三次原因各不相同。第一次是sender选错了人。接口返回成功任务也创建了但那位成员根本没有这个群客户端里看不到待发送任务自然也不会发。解决方法是派单前校验群主身份。第二次是群状态过期。数据库里的群还在但实际群已经解散了任务派下去成员点发送时报错。解决方法是靠回调事件及时更新状态并且在派单前做一次轻量校验。第三次是内容触发了限制。文案里有些表述被判定为不合规接口没报错但消息在成员确认后被拦截了。这种情况只能靠内容预审来防把明显有风险的词提前过滤掉。7.3 几条实操心得第一条不要在业务高峰期做全量同步。群列表同步、详情刷新这类批量操作放在凌晨跑白天只做增量。第二条把任务说明写清楚。成员在客户端看到的只有你给的文案如果不说清楚“发到哪个群、什么时候发”执行质量会很差。我一般会在文案开头加一行内部提示比如“【内部说明】请发送至 3 月活动群勿发其他群”这行字在正式发送前可以删掉。第三条留一条人工通道。再完善的自动化也会有个位数比例的漏发运营侧要有一个能看到全量任务状态的页面能手动催、手动标记完成。这个页面做起来不难但能省掉大量沟通成本。第四条定期核对配额。企业规模变化、业务线增加都会让配额消耗变快。每个月看一次消耗趋势提前扩容或者调整发送策略比临时救火强。第五条把群主当成用户来运营。这套系统的实际执行者是各位群主他们的体验决定了最终效果。任务太多、文案太乱、催办太频繁都会导致执行率下降。适当做减法比不断加功能更有价值。我个人在实际项目里的体会是企业微信外部群消息推送这件事技术难度集中在“边界认知”上而不是代码本身。想清楚哪些能做、哪些不能做、不能做的部分用什么方式绕过方案自然就出来了。真正写代码的时间可能只占整个项目的三成剩下七成都在跟业务方对齐预期、跟运营方打磨流程。把这个心理预期摆正项目推进起来会顺很多。
阅读完成 · 觉得有帮助？
