Docs
文档目录

消息

消息(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 抽象模型下:

  1. 三大通道、11 种主流发送提供商(Providers)开箱即用:

    • Push 移动端推送:集成 Firebase Cloud Messaging(FCM)与 Apple Push Notification service(APNs)。

    • Email 邮件通知:集成 Mailgun、SendGrid、Resend 与标准自定义 SMTP。

    • SMS 短信触达:集成 Twilio、MSG91、Telesign、Textmagic 与 Vonage。

  2. 基于用户通知目标(Targets)的精准与群组投递:与项目 Auth(认证) 模块深度打通,每个终端用户(如 user_zhangwei_001)名下自动维护验证过的邮箱、手机号与多台移动设备 Push Token;支持按 Topics(主题) 批量广播或直接勾选单个 Target 定向发送。

  3. 灵活的投递排期与生命周期控制:支持保存为草稿(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)以及异步投递状态机三者的协同:

消息:流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

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 所示):

  1. 浏览器直达 URL:在项目路径后直接访问 /console/project-{region}-{project}/messaging(例如生产样板项目地址为 https://appbuild.oceanbase.com/console/project-default-enterprise-ai-hub-210/messaging)。

  2. 控制台快捷键命令中心:在控制台任意页面呼出全局命令搜索框,输入 messaging、topics 或 create message 直接跳转。

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

功能详解与操作指南

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

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

  1. 访问 /console/project-default-enterprise-ai-hub-210/messaging/providers,点击右上角 Create provider。

  2. 选择消息渠道(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(电子邮件)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。
  1. 管理与启停 Provider:

    • 创建完成后进入 Provider 详情页,确认顶部的状态开关处于 Enabled(已启用) 状态——Messaging 投递引擎在发送某渠道消息时,只会路由给当前处于 Enabled 状态的 Provider。

    • 所有 API Key、密码与 .p8/.json 私钥在保存后均由服务端加密存储,界面单向掩码不回显。

    • 删除风险:在详情页底部 Danger zone 删除 Provider 将永久移除该通道配置,不可撤销。

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

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

  1. 切换到 Topics 页签(路径 /messaging/topics,如图 1 所示),点击 Create topic,输入主题名称(如 enterprise-vip-ticket-notify)与可选自定义 Topic ID。

  2. 添加订阅者目标(Create subscriber):

    • 点开新建的主题详情页,在 Subscribers 页签点击 Create subscriber。

    • 在弹窗中展开项目 Auth 用户列表,勾选目标用户下具体的 Targets(例如勾选 user_zhangwei_001 的企业邮箱 Target 和移动端 Push Target)。支持勾选多条订阅记录进行批量移除。

  3. 配置客户端自助订阅权限(Subscription access):

    • 切换到主题详情的 Settings 页签,在 Subscription access 区域添加角色选择器(例如添加 users 或 team:support_team),控制哪些前端登录用户可以通过客户端 SDK 自主订阅该主题。

  4. 查看审计日志(Activity):切换到 Activity 页签,可追溯该主题的创建、改名与订阅者增删审计流水。

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

  1. 切换到 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 字符• 向导右侧提供实时手机锁屏通知预览图;
• 可选绑定 Media(存储桶内的图片文件) 实现富媒体大图推送;
• 可选添加 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 状态)。请按以下步骤定位根因:

  1. 在 Messages 列表中点击该条 failed 消息右侧的 Details / View logs 打开详情页。

  2. 查看错误日志明细:

    • 若提示 No enabled provider found:请前往 Providers 页签检查对应渠道(Email/SMS/Push)的提供商是否已创建且右上角开关处于 Enabled 状态。

    • 若提示第三方通道鉴权或投递报错(如 SMTP 535 认证失败、FCM Token 失效 Unregistered):在日志中核对具体失败的 Target ID,更新 Provider 凭据或清理已失效的客户端设备 Token。

相关文档