消息
消息(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 抽象模型下:
- 三大通道、11 种主流发送提供商(Providers)开箱即用:
- Push 移动端推送:集成 Firebase Cloud Messaging(FCM)与 Apple Push Notification service(APNs)。
- Email 邮件通知:集成 Mailgun、SendGrid、Resend 与标准自定义 SMTP。
- SMS 短信触达:集成 Twilio、MSG91、Telesign、Textmagic 与 Vonage。
- 基于用户通知目标(Targets)的精准与群组投递:与项目 Auth(认证) 模块深度打通,每个终端用户(如
user_zhangwei_001)名下自动维护验证过的邮箱、手机号与多台移动设备 Push Token;支持按 Topics(主题) 批量广播或直接勾选单个 Target 定向发送。 - 灵活的投递排期与生命周期控制:支持保存为**草稿(
draft)反复校对、设定未来时间定时发送(scheduled,到点前可隨時改期或撤回草稿)以及立即入队发送(processing → sent / failed)**。
| 核心子页签 | 控制台路由路径 | 核心管理对象 | 所需写权限 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 -- "提供底层发送通道" --> Processing1. 消息五大生命周期状态与可执行操作矩阵
每条消息(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 所示):
- 浏览器直达 URL:在项目路径后直接访问
/console/project-{region}-{project}/messaging(例如生产样板项目地址为https://appbuild.oceanbase.com/console/project-default-enterprise-ai-hub-210/messaging)。 - 控制台快捷键命令中心:在控制台任意页面呼出全局命令搜索框,输入
messaging、topics或create message直接跳转。
2. 与项目 Auth 用户 Targets 及自定义 SMTP 的关系
- 收件人来源(Auth Targets):Messaging 的所有接收对象均取自项目 Auth → Users → 目标用户 → Targets 页签(详见消息目标)。创建 Topic 订阅者时,勾选的也是用户的具体通知目标(如用户的某个邮箱或某台 iPhone 的 Push Token),而非抽象的用户 ID。
- 平台/项目系统邮件 vs Messaging 业务邮件:
- 项目 Settings → SMTP 配置的服务器用于发送 Auth 模块的系统验证邮件、密码重置邮件与团队邀请邮件。
- Messaging → Providers 中创建的 Email Provider(支持 Mailgun、SendGrid、Resend、SMTP)则专门用于向终端用户发送业务通知、工单状态提醒与运营广播邮件,两套配置彼此独立。
功能详解与操作指南
1. 配置并启用发送提供商(Providers)
在发送任何渠道的消息之前,必须先在该渠道下创建并启用(Enabled)至少一个发送提供商:
- 访问
/console/project-default-enterprise-ai-hub-210/messaging/providers,点击右上角 Create provider。 - 选择消息渠道(
Email、SMS或Push),填写 Name 与自定义 **Provider ID($id)**,并对照向导内置的「如何获取第三方凭据」指引填写必填字段:
| 消息渠道 | 可选 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(电子邮件) | SMTP | Server host、Port、Username、Password、Encryption(TLS/SSL/None)、发件人邮箱与名称 | 适合对接企业自建邮局、阿里云邮件推送或腾讯企业邮。 |
| SendGrid / Resend | API Key + From Email(发件邮箱) + From Name(发件人名称) + 可选 Reply-To | 发件邮箱域名需已在 SendGrid / Resend 侧完成 SPF/DKIM 验证。 | |
| Mailgun | API Key + Domain(发信域名) + EU Region 区域开关 + 发件邮箱与名称 | 若 Mailgun 域建在欧盟区,需打开 EU Region 开关。 | |
| SMS(手机短信) | Twilio / Vonage / Telesign / Textmagic | 平台账号凭据(如 Twilio Account SID + Auth Token)+ From Number / Sender ID(发信号码) | 接收手机号需包含国际区号(E.164 格式,如 +86...)。 |
| MSG91 | Auth Key + Sender ID + Template ID(短信模板 ID,必填) | 严格匹配报备通过的短信模板 ID。 |
- 管理与启停 Provider:
- 创建完成后进入 Provider 详情页,确认顶部的状态开关处于 Enabled(已启用) 状态——Messaging 投递引擎在发送某渠道消息时,只会路由给当前处于
Enabled状态的 Provider。 - 所有 API Key、密码与
.p8/.json私钥在保存后均由服务端加密存储,界面单向掩码不回显。 - 删除风险:在详情页底部 Danger zone 删除 Provider 将永久移除该通道配置,不可撤销。
- 创建完成后进入 Provider 详情页,确认顶部的状态开关处于 Enabled(已启用) 状态——Messaging 投递引擎在发送某渠道消息时,只会路由给当前处于
2. 创建订阅主题(Topics)与管理订阅者(Subscribers)
当需要向一组具有相同属性的终端用户(例如“全部二线值班客服坐席”或“订阅了系统维护公告的 VIP 客户”)群发通知时,使用 Topics 可避免每次手动逐个勾选收件人:
- 切换到 Topics 页签(路径
/messaging/topics,如图 1 所示),点击 Create topic,输入主题名称(如enterprise-vip-ticket-notify)与可选自定义 Topic ID。 - 添加订阅者目标(Create subscriber):
- 点开新建的主题详情页,在 Subscribers 页签点击 Create subscriber。
- 在弹窗中展开项目 Auth 用户列表,勾选目标用户下具体的 Targets(例如勾选
user_zhangwei_001的企业邮箱 Target 和移动端 Push Target)。支持勾选多条订阅记录进行批量移除。
- 配置客户端自助订阅权限(Subscription access):
- 切换到主题详情的 Settings 页签,在 Subscription access 区域添加角色选择器(例如添加
users或team:support_team),控制哪些前端登录用户可以通过客户端 SDK 自主订阅该主题。
- 切换到主题详情的 Settings 页签,在 Subscription access 区域添加角色选择器(例如添加
- 查看审计日志(Activity):切换到 Activity 页签,可追溯该主题的创建、改名与订阅者增删审计流水。
3. 创建、排期与发送多渠道消息(Messages)
- 切换到 Messages 页签(路径
/messaging),点击右上角 Create message 下拉按钮,选择拟发送的渠道类型(Email / SMS / Push),进入三步创建向导(Message → Targets → Schedule):
第一步:编写消息内容(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)
- 在向导第二步中,可添加一个或多个 Topics(主题),也可直接勾选具体的用户 Targets(两者可组合使用,但至少需选择一个主题或一个目标)。
- 渠道自动匹配规则:若你创建的是
Email消息并选择了一个包含邮箱、手机号和 Push Token 混合订阅者的 Topic,系统在投递时会自动只筛选出该 Topic 下的 Email Targets 进行发送。
第三步:选择发送时机(Schedule)并核验结果
- 立即发送(Now):点击发送并在确认弹窗(显示预估触达目标总数及不可逆提示)中确认,消息立即进入
processing状态;列表每 2 秒自动刷新,完成后变为sent或failed。 - 定时发送(Schedule):指定未来的日期与时间提交,消息进入
scheduled状态;到期前可随时在详情页点击 Reschedule 改期或 Cancel scheduling 退回草稿。 - 保存草稿(Save as draft):保存为
draft状态,后续确认无误后再正式发送。
常见问题与排障
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 状态)。请按以下步骤定位根因:
- 在 Messages 列表中点击该条
failed消息右侧的 Details / View logs 打开详情页。 - 查看错误日志明细:
- 若提示
No enabled provider found:请前往 Providers 页签检查对应渠道(Email/SMS/Push)的提供商是否已创建且右上角开关处于 Enabled 状态。 - 若提示第三方通道鉴权或投递报错(如 SMTP 535 认证失败、FCM Token 失效
Unregistered):在日志中核对具体失败的 Target ID,更新 Provider 凭据或清理已失效的客户端设备 Token。
- 若提示