企业每天都在业务系统里产生大量事件。
一票订单状态变了。
客户费用已经确认。
某票货物出现异常。
报关资料还没有补齐。
某个内部任务需要相关人员及时处理。
这些信息原本已经存在于业务系统里。
但真正需要通知客户或者员工时，很多企业依然在做一件非常传统的事情：
人工复制，再发到群里。
业务员打开系统。
复制订单号和状态。
再打开企业微信或者 QQ。
找到对应客户群。
粘贴。
发送。
一天只有几条消息的时候，这样做似乎没有什么问题。
但当订单越来越多、客户群越来越多之后，很快就会出现：
消息忘记发。
群发错了。
同一条通知重复发。
员工下班后没人发。
系统已经产生异常，但群里过了很久才知道。
所以，立刻智能体增加了一个更加适合系统集成的能力：
推送通知 API。
让业务系统产生事件之后，可以直接调用接口，将消息自动送到对应的企微群或 QQ 群。
一个接口，同时支持企微群和 QQ 群
推送通知统一使用：
POST /api/v1/notifications
也就是说，企业自己的 ERP、TMS、货代系统、订单系统或者其他内部业务平台，不需要分别开发两套：
企业微信推送接口。
QQ 群推送接口。
业务系统只需要按照统一的数据结构，把需要发送的通知提交给立刻智能体。
之后由立刻智能体根据目标群所属渠道，完成实际消息投递。
一次典型的推送请求主要会包含几个核心信息：
biz_msg_id
业务消息唯一编号。
target
这条消息需要发给谁。
text
实际需要发送的通知内容。
urgent
是否属于紧急消息。
可以简单理解为：
这是哪一条业务消息？
要发到哪里？
发什么内容？
是不是紧急通知？
调用方只需要关心自己的业务逻辑。
至于最终是通过企业微信机器人发送，还是通过 QQ 机器人发送，则交给立刻智能体统一处理。
推送目标怎么确定？
系统知道“要发送一条通知”还不够。
更重要的是：
这条消息到底应该发到哪个群？
立刻智能体提供了两种主要的定位方式。
方式一：按公司代码定位
如果企业已经建立了客户公司与群之间的关系，可以通过：
company_code
进行业务定位。
例如：
业务系统知道这票订单属于客户：
CUS000128
那么推送时可以直接将这个公司代码作为目标条件。
立刻智能体再根据已经维护好的群关系，找到对应的推送群。
这种方式比较适合：
业务系统天然以客户、供应商或公司主体作为数据中心的场景。
调用方不需要知道具体群号是什么。
只需要知道：
这条通知属于哪个客户。
方式二：直接按群定位
另外一种方式更加直接。
可以通过：
channel + instance_id + room_id
指定具体群。
其中：
channel
表示消息渠道，例如企微或者 QQ。
instance_id
表示对应接入实例。
room_id
表示具体群标识。
这种方式适合业务系统本身已经知道目标群的场景。
例如某个项目群。
某个内部通知群。
某个固定客户服务群。
这时可以直接指定：
消息就发到这个群。
两种模式并不冲突。
企业可以根据自己的业务系统结构选择更合适的定位方式。
不知道有哪些群？可以先查询群清单
对于接口调用方来说，还有一个很实际的问题：
当前到底有哪些群可以推送？
因此，立刻智能体提供群清单接口：
GET /api/v1/rooms
业务系统可以通过接口获取已经接入的群信息。
同时还可以根据条件进行筛选，例如：
- 渠道
- 推送状态
- 公司代码
这样，在进行系统集成或者目标匹配时，就不需要人工去后台一个个复制群 ID。
接口还会返回群当前的推送状态。
例如：
ready
表示当前具备正常推送条件。
blocked
表示该群当前无法正常推送。
unknown
表示当前状态暂时无法确认。
这一点非常重要。
因为：
群存在，不代表此刻一定可以发送消息。
机器人可能被移出群。
授权可能发生变化。
接入实例可能离线。
群本身的状态也可能变化。
所以推送系统不能只管理一个静态的“群编号”。
还需要知道：
这个群当前能不能发。
为什么一定要有 biz_msg_id？
在消息推送系统里，有一个很容易被忽略的问题：
重复发送。
假设业务系统调用接口之后，因为网络超时，没有收到成功响应。
这时候调用方并不知道：
消息到底有没有发出去？
最常见的处理就是：
再请求一次。
但如果上一条实际上已经成功发送，那么客户群里就可能看到：
同一条订单提醒。
连续发了两遍。
甚至更多。
所以推送接口使用：
biz_msg_id
作为业务消息的唯一标识。
对于同一个 biz_msg_id，系统会进行幂等处理。
也就是说：
同一条业务消息，不会因为重复调用而被重复投递。
这对于系统接口来说非常重要。
因为业务系统就可以更加放心地进行：
- 网络失败重试
- 超时重试
- 服务恢复后重新执行
- 任务队列重新消费
即使服务发生重启，只要业务消息 ID 不变，就可以尽可能避免因为技术重试造成重复通知。
不是任何时间都适合给客户发消息
接口自动化以后，还有一个新的问题。
业务系统是 24 小时运行的。
但客户不一定希望：
凌晨 2 点收到普通订单通知。
晚上 11 点收到一条并不紧急的费用提醒。
所以，立刻智能体支持配置：
消息推送时间窗口。
例如企业可以设置：
普通通知只允许在指定时间范围内发送。
如果业务系统在窗口以外提交消息，并不代表消息一定被丢弃。
系统可以将其自动进入排期。
等到下一个允许推送的时间窗口，再继续发送。
这样业务系统仍然可以：
事件发生时立即提交。
而实际什么时候打扰客户，则交给推送策略控制。
真正紧急的消息，可以使用 urgent
当然，有些消息不能等。
比如：
重要业务异常。
临时截单变化。
重大运输异常。
需要立即处理的内部事件。
这种情况下，可以通过：
urgent
标记紧急消息。
紧急消息可以根据实际配置绕过普通推送时间窗口的限制。
也就是说：
普通信息遵守发送时间。
紧急信息优先确保时效。
这样就不用为了照顾异常场景，把所有消息都设置成全天随时发送。
自动推送，也要有配额和限速
如果系统完全不限制自动消息，另一个风险就是：
短时间推送过多。
例如一次批量任务更新了几千票订单。
如果程序瞬间把几千条通知全部提交到群里，不仅客户体验不好，也可能触发平台侧的频率限制。
因此，立刻智能体会对自动推送增加相应的配额和速度控制。
例如：
每日发送配额
控制一定周期内可以投递的消息数量。
对于 QQ 群，还可以进一步进行：
分钟级发送限速。
如果短时间消息过多触发限速，并不意味着这些消息全部失败。
系统可以将部分消息延迟，并重新安排后续发送时间。
也就是说，系统会尽量把：
“现在不能发”
转化为：
“稍后再发”。
而不是简单丢弃。
系统调用成功，不等于消息一定已经送达
做接口集成时，还有一个经常出现的误区。
业务系统调用：
POST /api/v1/notifications
接口返回成功。
是不是就代表客户一定已经收到消息？
不一定。
因为：
接口接收成功
和：
最终消息投递成功
本身是两个不同阶段。
例如接口收到消息之后，可能发现：
目标群不存在。
群当前被阻塞。
超过当天配额。
当前不在允许推送的时间窗口。
触发 QQ 群限速。
对应机器人暂时不可用。
所以，立刻智能体还提供相应的：
投递结果 / 回执查询能力。
业务系统可以继续查询这条通知当前处于什么状态。
例如：
等待发送。
已经排期。
发送成功。
被跳过。
发送失败。
如果没有正常投递，系统还可以保留相应原因。
例如：
- 群不存在
- 当前群被阻塞
- 超出发送配额
- 限速等待
- 其他推送条件不满足
这样企业自己的业务系统也可以继续判断：
这条通知是不是已经真正完成。
要不要人工处理。
要不要进入异常列表。
最常见的场景：订单状态自动通知
对于国际物流企业来说，最直接的应用就是：
订单状态变更通知。
比如系统中的订单从：
已订舱
变成：
已放舱
业务系统触发事件。
自动调用推送接口。
消息就可以进入对应的客户服务群：
【订单状态更新】
工作号：SH260928001
当前状态：已放舱
船名航次：XXX / V.028E
整个过程不再需要业务员：
复制。
打开 QQ。
找群。
粘贴。
发送。
系统产生业务变化的同时，就可以触发对应客户通知。
费用确认，也可以直接进入客户群
另外一个常见场景是：
费用确认。
例如系统生成了一份待确认账单。
过去可能需要财务或者客服手工把信息发到客户群。
现在可以由业务系统自动提交通知：
【费用确认提醒】
工作号：SH260928001
本票费用已生成，请及时确认。
如果后续还有客户查询链接，也可以一起组合到通知内容里。
这样：
账单产生
和：
通知客户
就可以形成一条自动化链路。
异常预警，更适合使用自动推送
相比普通状态通知，异常类消息对及时性的要求通常更高。
例如：
货物状态异常。
报关资料缺失。
车辆长时间停留。
订单关键节点超时。
某项业务出现风险。
业务系统本身可能已经能够识别这些异常。
但如果异常只停留在系统后台，没有人及时看到，那么预警本身的价值就会大幅降低。
通过推送通知 API，可以把：
系统发现异常
继续连接到：
立即通知相关人员。
对于非常紧急的情况，还可以结合 urgent 使用。
这样异常不再只是后台的一条红色记录。
而可以真正主动找到需要处理的人。
内部通知也可以使用同一套接口
推送 API 不一定只能用于客户群。
企业内部群同样适用。
比如：
- 当日重点订单提醒
- 财务未核销提醒
- 操作异常
- 系统维护通知
- 重要内部公告
- 待处理任务
业务系统可以直接指定内部 QQ 群或者企微群。
也就是说，这套接口本质上解决的是：
业务系统如何把一条重要事件，可靠地送到一个群里。
至于这个群是：
客户群。
供应商群。
项目群。
还是公司内部群。
由企业自己决定。
为什么要同时支持企业微信和 QQ？
现实里，很多企业并不是只使用一种沟通工具。
有些客户习惯企业微信。
有些老客户一直使用 QQ。
公司内部又可能使用另外一套群。
如果每一个渠道都由业务系统单独开发接口，会带来很多重复工作。
开发需要分别维护。
异常处理逻辑不同。
限速规则不同。
推送记录也分散。
立刻智能体希望把这些差异放在统一的推送层处理。
业务系统只提交：
我要发什么。
我要发给谁。
至于最后通过：
企微群还是 QQ 群
完成投递，由立刻智能体继续处理。
这样未来企业再增加新的消息场景时，不需要为每一个业务功能重新开发一遍渠道逻辑。
使用推送通知 API，需要什么条件？
要使用推送通知 API，首先需要开通对应的接口及推送权限。
同时，不同渠道需要完成相应的机器人接入。
如果要向企业微信群推送：
需要对应的企微机器人具备正常发送条件。
如果要向 QQ 群推送：
需要完成 QQ 机器人接入，并保证目标群当前具备推送条件。
需要特别注意：
群的推送状态并不是永久不变的。
机器人可能离线。
群关系可能发生变化。
授权可能失效。
发送条件也可能随着平台状态发生变化。
因此，更稳妥的集成方式是：
业务系统在需要时查询群清单和推送状态。
发送后再结合投递结果确认最终状态。
而不是认为：
只要曾经绑定成功，这个群以后就永远可以发送。
从“系统里发生了什么”，到“相关的人马上知道”
企业做信息化以后，很多业务动作其实早就已经数字化了。
订单状态。
账单。
异常。
节点。
任务。
都已经存在系统里。
但如果这些信息最终还需要员工：
看到 → 复制 → 找群 → 粘贴 → 发送
那么业务系统和客户沟通之间，实际上仍然存在一段人工断点。
推送通知 API 做的事情，就是把这段连接起来。
业务事件发生。
↓
系统调用通知接口。
↓
立刻智能体定位目标群。
↓
根据时间窗口、配额和限速规则进行调度。
↓
通过企微机器人或 QQ 机器人完成发送。
↓
业务系统再查询实际投递结果。
于是原来依赖人工完成的一条消息，开始变成一条真正可自动运行的业务流程。
让重要业务通知不再等人转发，而是在应该出现的时候，自动出现在应该出现的群里。