企业微信API接口如何处理业务通知？从事件触发到消息推送的实现方式

业务通知是企业微信二次开发里最实用的能力之一。审批待办、回款提醒、库存预警、系统告警——这些发生在业务系统里的事件，通过企微 API 推到对应的人或群，比邮件和短信都更即时。这篇讲讲从事件触发到消息推送这条链路怎么搭。

一、通知系统的整体结构

一个完整的通知系统不是"调发消息接口"这么简单，至少要包含三个部分：

• 事件源：业务系统的各种触发器，审批流、定时任务、监控告警

• 通知引擎：接收事件、按规则路由到目标、组装消息内容

• 推送通道：最终调企微接口把消息发出去

三者解耦的好处是事件源不关心发到哪、发什么格式，通知引擎不关心业务逻辑，推送通道只管可靠送达。加新通知类型时只改规则配置，不动代码。

二、事件到通知的路由

同一个业务事件，不同角色该收到不同内容。比如订单回款这个事件：

• 销售：收到回款金额和客户名

• 销售主管：收到团队回款汇总

• 财务：收到对账明细

路由规则建议做成配置化，按"事件类型 + 角色模板"匹配：

ROUTING_RULES = {
"payment_received": [
{"role": "sales", "template": "sales_receipt", "target": "personal"},
{"role": "sales_mgr", "template": "team_summary", "target": "group"},
{"role": "finance", "template": "finance_detail", "target": "personal"},
],
"system_alert": [
{"role": "oncall", "template": "alert_brief", "target": "group", "mention": True},
]
}

target 决定发到个人还是群。发个人走 message/sendText，conversationId 带对方的用户 ID；发群走同样的接口，conversationId 带 roomId。需要 @ 人的告警类通知，要换用 message/sendRichText 富文本接口，文本接口不支持 @。

三、消息内容怎么组装

通知内容最忌讳大段文字糊脸，企微里没人愿意看长消息。组装时有几个原则：

• 关键信息前置：金额、时间、客户名放最前面，一眼能看到重点

• 链接卡片代替长文本：详情用 message/sendLink 发链接卡片，正文只放摘要，点进去看全文

• 分级标题：多条信息合并推送时用换行和符号分隔，别堆成一坨

链接卡片是通知场景里最实用的消息类型，正文放一句话摘要，卡片标题和描述做引导，点进去就是业务系统的详情页。比起贴一长串文字，体验好太多。

四、推送通道的可靠性

通知系统的核心指标是"必达"。业务事件发生了，消息没送达就是事故。推送通道要处理几个情况：

重复事件。业务系统可能因重试推同一个事件，通知引擎要按事件 ID 幂等。同一个事件只组装一次消息，只发一次。建议在事件入口建唯一约束，重复事件直接丢弃。

发送失败。接口返回非 0 的 code 时进重试队列，按指数退避重试。但要注意：发送类接口超时后先确认上一次是否成功，盲重试会导致客户收到重复消息。重试前查发送记录，已成功就跳过。

频率控制。告警风暴场景下同一目标可能短时间收到大量通知，要在推送通道侧做聚合和限流。同一群每分钟最多 5 条告警，超出的合并成一条汇总。接口侧返回 429 时整体降频，不要硬冲。

def send_with_control(target, message):
# 频率检查
key = f"rate:{target}"
count = redis.incr(key)
if count == 1: redis.expire(key, 60)
if count > 5:
buffer.append(target, message) # 进聚合缓冲
return
# 串行发送，同一 appid 不并发
with send_lock[target.appid]:
result = api.send(target, message)
if result.code != 0:
retry_queue.push(target, message, backoff="exponential")

五、几种典型通知场景

不同场景的通知，处理重点不一样：

场景

特点

设计重点

审批待办这类通知还有个升级机制要做：一级审批人 2 小时没处理，通知升级到二级审批人；再没处理升级到部门负责人。链路不长但能解决"通知发了没人看"的常见痛点。

六、和回调事件的区别

这里说的业务通知是"业务系统主动推"，和企微侧的回调事件是两个方向。企微侧的 message.received 这类回调是"客户行为触发的入站事件"，业务通知是"内部系统触发的出站动作"。两者都用消息接口，但触发源不同。

如果想把企微侧的回调事件也纳入通知体系（比如客户加了好友就通知销售），那是另一个场景：回调服务收到事件 → 通知引擎按规则匹配 → 推送通道发给对应销售。这时候通知引擎是回调事件的消费者之一。回调机制本身的细节可以看Eyun开发文档，可订阅的事件类型、推送头、报文字段在里面有完整描述。

写在最后

通知系统看着简单，做扎实不容易。关键在路由规则的可配置化、推送通道的可靠性、频率控制的合理性。这三块做到位，通知系统就能真正替人跑腿，而不是成为新的麻烦来源。