AgentbaseDocs
文档目录

消息

消息(Messaging)是 Agentbase 2.10.0 内置的多渠道终端用户触达引擎,支持通过统一的控制台向导与服务端接口向项目终端用户发送 电子邮件(Email)、手机短信(SMS) 与 移动端推送通知(Push Notification),并提供 发送提供商(Providers) 凭据托管、订阅主题(Topics) 群组广播、订阅者目标(Subscribers / Targets) 精细投递以及立即发送、定时排期(Schedule)与草稿(Draft)全状态机管理。

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

功能概述

在企业智能客服与知识中台(如生产样板项目 enterprise-ai-hub-210)的实际运营中,当客户提交的高优技术支持工单(如 TK-20261022-001)状态流转、或者智能体识别出复杂疑难问题转交二线专家坐席时,系统需要及时通过邮件、短信或 App 弹窗通知相关客户与值班工程师。

Agentbase Messaging 将异构第三方通道收口到统一的 Provider → Topic / Target → Message 抽象模型下:

核心子页签控制台路由路径核心管理对象所需写权限 Scope / 组织角色
Messages(消息列表)/console/project-{region}-{project}/messaging创建 Email / SMS / Push 消息、管理草稿与定时排期、查看投递状态与错误日志messages.write(owner / admin / developer / editor;只读角色仅可查看)
Topics(订阅主题)/console/project-{region}-{project}/messaging/topics创建主题、从 Auth 用户 Targets 中添加/移除订阅者、配置客户端订阅权限(Subscription access)topics.write
Providers(发送提供商)/console/project-{region}-{project}/messaging/providers创建与启停第三方 Email / SMS / Push 通道凭据实例providers.write

核心概念与架构

在 Messaging 模块中,一条消息能够成功送达终端用户,依赖于已启用的通道 Provider、合法的用户通知目标(Target)或订阅主题(Topic)以及异步投递状态机三者的协同:

flowchart TB
    subgraph AuthAndTargets["上游:Auth 终端用户与通知目标 (Targets)"]
        AuthUser["Auth 终端用户<br/>(例如: user_zhangwei_001 / user_lina_002)"]
        Targets["用户的三类 Targets:<br/>1. Email Target (邮箱地址)<br/>2. SMS Target (手机号码)<br/>3. Push Target (FCM/APNs 设备 Token)"]
        AuthUser --> Targets
    end

    subgraph TopicsAndProviders["中游:主题订阅 (Topics) 与通道提供商 (Providers)"]
        Topic["Topic 订阅主题 (例如: vip_ticket_alerts)<br/>Subscribers = 绑定的具体用户 Targets<br/>+ Subscription access 客户端订阅角色"]
        Provider["已启用的 Providers (Enabled=true):<br/>• Email: SMTP / SendGrid / Mailgun / Resend<br/>• SMS: Twilio / Vonage / MSG91 / Telesign / Textmagic<br/>• Push: FCM (.json) / APNs (.p8)"]
        Targets -- "添加为订阅者" --> Topic
    end

    subgraph MessageLifecycle["下游:Message 创建与投递状态机"]
        Draft["draft (草稿态)<br/>可自由修改正文/目标、转定时或立即发送"]
        Scheduled["scheduled (已排期定时态)<br/>等待到达排期时间"]
        Processing["processing (异步队列投递中)<br/>控制台列表每 2 秒自动轮询刷新"]
        Sent["sent (投递成功)<br/>至少 1 个目标投递成功"]
        Failed["failed (投递失败)<br/>无可用 Provider / 无有效目标 / 含部分失败"]

        Draft -- "Schedule 定时" --> Scheduled
        Scheduled -- "Cancel scheduling (取消排期)" --> Draft
        Scheduled -- "Reschedule (改期)" --> Scheduled
        Draft -- "Send Now (不可逆确认)" --> Processing
        Scheduled -- "到达排期时间" --> Processing
        Processing --> Sent
        Processing --> Failed
    end

    Topic -- "按渠道匹配目标" --> Processing
    Targets -- "直接指定目标" --> Processing
    Provider -- "提供底层发送通道" --> Processing

1. 消息五大生命周期状态与可执行操作矩阵

每条消息(Message)从创建到终态均处于以下五种状态之一。由于短信、邮件与移动端推送一旦发出即无法从用户手机上物理撤回,系统在不同状态下严格约束可执行的操作:

状态标识状态含义与界面表现允许执行的操作不可逆风险与边界说明
**draft**草稿态:仅保存在数据库中,未进入发送队列编辑标题/正文、增删收件 Topics/Targets、转为定时发送(Schedule)、立即发送(Send message)、删除草稿最安全的校对状态;群发重要通知前建议先保存为草稿核对。
**scheduled**已排期态:已设定未来发送时间,等待调度器触发Reschedule(修改定时发送时间)、Cancel scheduling(取消排期,**消息安全退回 draft 草稿态**可继续编辑正文)、删除记录(同时取消投递)在排期时间到达前随时可无损撤回或改期。
**processing**投递中:已进入后台 Worker 发送队列,控制台列表每 2 秒自动轮询刷新状态禁止编辑、不显示删除卡片(等待异步投递完成)立即发送确认弹窗明确提示 This action is irreversible.(操作不可逆)。
**sent**已送达:至少有一个目标(Target)成功完成投递查看投递详情、从列表中 Delete(删除记录)删除 sent 记录仅从 Console 列表中移除历史流水,绝不会撤回或召回已送达用户设备的消息。
**failed**投递失败:当前渠道无已启用的 Provider、所选主题下无该渠道有效 Target,或第三方通道返回错误(**注意:部分目标失败同样计入 failed,无单独的“部分成功”状态**)点击 Details / View logs 查看逐条错误明细;从列表中删除记录已进入 processing / sent / failed 的记录不能直接原地修改正文重发,需新建一条消息重发。

角色、入口与关联关系

1. 控制台访问入口说明(直达 URL 与命令中心)

重要导航提示:在 Agentbase 2.10.0 中,为了精简左侧主导航栏,Messaging(消息)模块默认不在左侧边栏直接展示图标(属于构建内置隐藏导航项),但其前端路由与后端服务完整可用。

你可以通过以下两种方式随时进入 Messaging 工作台(如图 1 所示):

2. 与项目 Auth 用户 Targets 及自定义 SMTP 的关系

功能详解与操作指南

1. 配置并启用发送提供商(Providers)

在发送任何渠道的消息之前,必须先在该渠道下创建并启用(Enabled)至少一个发送提供商:

消息渠道可选 Provider 类型必填凭据与核心配置字段生产配置注意事项
Push(移动端推送)FCM(Firebase)上传 Google Firebase Service Account JSON(服务账号密钥 JSON 文件)确保客户端 Android / Web / iOS 应用集成的 Firebase 项目与该服务账号一致。
APNS(Apple)Team ID、Bundle ID、Key ID(密钥 ID)、上传 Apple **.p8 签名密钥文件、可选开启 Sandbox(沙盒测试环境开关)**生产发布(App Store)务必关闭 Sandbox 开关;开发真机调试开启 Sandbox。
Email(电子邮件)SMTPServer host、Port、Username、Password、Encryption(TLS/SSL/None)、发件人邮箱与名称适合对接企业自建邮局、阿里云邮件推送或腾讯企业邮。
SendGrid / ResendAPI Key + From Email(发件邮箱) + From Name(发件人名称) + 可选 Reply-To发件邮箱域名需已在 SendGrid / Resend 侧完成 SPF/DKIM 验证。
MailgunAPI Key + Domain(发信域名) + EU Region 区域开关 + 发件邮箱与名称若 Mailgun 域建在欧盟区,需打开 EU Region 开关。
SMS(手机短信)Twilio / Vonage / Telesign / Textmagic平台账号凭据(如 Twilio Account SID + Auth Token)+ From Number / Sender ID(发信号码)接收手机号需包含国际区号(E.164 格式,如 +86...)。
MSG91Auth Key + Sender ID + Template ID(短信模板 ID,必填)严格匹配报备通过的短信模板 ID。

2. 创建订阅主题(Topics)与管理订阅者(Subscribers)

当需要向一组具有相同属性的终端用户(例如“全部二线值班客服坐席”或“订阅了系统维护公告的 VIP 客户”)群发通知时,使用 Topics 可避免每次手动逐个勾选收件人:

3. 创建、排期与发送多渠道消息(Messages)

第一步:编写消息内容(Message)

渠道类型必填内容字段字符长度与格式约束渠道专属增强配置
Email(邮件)Subject(邮件主题) + Message(邮件正文)支持纯文本或富文本 HTML可开启 HTML mode 开关发送排版精美的 HTML 邮件;可选自定义 Message ID。
SMS(短信)Message(短信正文)**最长 900 字符**建议精简文案并包含合规签名,避免超长短信被运营商拆条计费。
Push(移动端推送)Title(通知标题) + Body(通知正文)**正文最长 1000 字符**• 向导右侧提供实时手机锁屏通知预览图;<br/>• 可选绑定 Media(存储桶内的图片文件) 实现富媒体大图推送;<br/>• 可选添加 Custom data(自定义 Key-Value 键值对),该数据对终端用户不可见,供客户端 App 点击通知后读取并跳转到具体工单详情页(如 {"ticketId": "TK-20261022-001"})。

第二步:选择收件对象(Targets)

第三步:选择发送时机(Schedule)并核验结果

常见问题与排障

Q1:为什么我在项目左侧导航栏里找不到“Messaging / 消息”菜单项?

原因与排查步骤: 在当前 Agentbase 2.10.0 版本中,为了保持主侧边栏紧凑,Messaging 属于默认隐藏的侧栏入口,但其前后端功能完全就绪。请直接在浏览器地址栏访问 /console/project-{region}-{project}/messaging(将 {region} 与 {project} 替换为实际值,如 /console/project-default-enterprise-ai-hub-210/messaging),或使用控制台全局命令搜索框快速进入。

Q2:在创建 Email 或 Push 消息的“选择收件对象(Targets)”步骤中,为什么我刚创建的 Topic 没有出现在可选列表里?

原因与排查步骤: 发送向导在筛选可选 Topics 时,会自动校验该主题下是否包含与当前所选消息渠道匹配的订阅目标(Targets)。例如,如果你正在创建一条 Push 推送通知,但你的 Topic 里目前只添加了用户的邮箱(Email Target)而没有任何移动设备 Push Token 订阅者,该 Topic 就不会出现在 Push 消息的可选发送对象中。请先前往 Messaging → Topics → 目标主题 → Subscribers,添加对应渠道的订阅目标后再创建消息。

Q3:消息发送后状态变为 failed,如何排查是全部失败还是部分收件人失败?

原因与排查步骤: 在 Messaging 状态机中,**只要存在投递错误(包括部分目标投递失败),整条消息状态都会标记为 failed**(系统不设单独的 partially_sent 状态)。请按以下步骤定位根因:

相关文档