agentbase-docs

消息

这是什么 / 何时用

消息发送面:Provider(通道凭据)→ Topic(订阅主题)/ Subscriber(订阅者)→ Message(Email / Push / SMS,支持草稿与排期发送),外加发送 / 通道 / 订阅日志。何时用:公告与通知(邮件 / 短信 / App 推送)、按主题群发、定时投放。

前置

使用骨架

关键参数与返回

调用关键参数返回
createTopictopicId、name、subscribeUsers?(是否要求用户授权订阅)Models.Topic
createSubscribertopicId、subscriberId、targetIdModels.Subscriber
createEmailmessageId、subject、content、topics?/users?/targets?、cc?/bcc?/attachments?、draft?、html?、scheduledAt?Models.Message(含 status、scheduledAt、deliveredTotal)
createPush / createSmsmessageId、内容字段、投递目标、draft?、scheduledAt?Models.Message
create*Provider通道凭据(providerId、name、auth 字段、enabled 等)Provider(secret 不回显)

消息查询支持按 scheduledAt、deliveredAt、deliveredTotal、status、description、providerType 属性过滤(queries 上限 100 条)。

错误与边界

SDK 类别差异

各语言调用示例

以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。

配置 Provider

消息发送面仅服务端暴露,Client SDK(Web)无此能力面,本卡省略 Web 页签。

import { Client, Messaging, ID } from 'agentbase-node-sdk';

const messaging = new Messaging(client);   // client 初始化见 server-sdk/nodejs.md

await messaging.createFcmProvider({
    providerId: ID.unique(),
    name: 'app-push',
    serviceAccountJSON: { type: 'service_account', project_id: 'my-project' },
    enabled: true
});
// Email:createMailgunProvider / createResendProvider / createSendgridProvider / createSmtpProvider
// SMS:createTwilioProvider / createTelesignProvider / createVonageProvider / createTextmagicProvider / createMsg91Provider
// Push 另有 createApnsProvider;均配 update*Provider / getProvider / listProviders / deleteProvider
// secret 类凭据保存后不回显,轮换经 update*Provider 重传

建 Topic

subscribe 控制哪些角色可订阅(缺省全部用户);Client SDK(Web)无此能力面,本卡省略 Web 页签。

const topic = await messaging.createTopic({
    topicId: ID.unique(),
    name: 'product-announcements',
    subscribe: ['users']   // 可订阅角色数组,最多 100 个
});

await messaging.listTopics();
await messaging.getTopic(topic.$id);
// updateTopic:调整名称与可订阅角色;deleteTopic:删除主题并级联删除订阅关系

订阅者

targetId 必须来自已存在用户的消息目标;Client SDK(Web)无此能力面,本卡省略 Web 页签。

const subscriber = await messaging.createSubscriber({
    topicId: topic.$id,
    subscriberId: ID.unique(),
    targetId: '<targetId>'   // 用户的消息目标(users.createTarget 或 messaging.listTargets)
});

await messaging.listSubscribers(topic.$id);
await messaging.getSubscriber(topic.$id, subscriber.$id);
await messaging.deleteSubscriber(topic.$id, subscriber.$id);   // 退订

创建消息(草稿与排期)

draft: true 仅保存不投递、可反复 update 后再发;scheduledAt 填未来 ISO 8601 时间即排期,到点由平台投递。Client SDK(Web)无此能力面,本卡省略 Web 页签。

const message = await messaging.createEmail({
    messageId: ID.unique(),
    subject: '10 月产品更新',
    content: '<h1>10 月产品更新</h1>',
    html: true,
    topics: [topic.$id],             // 投递目标 topics / users / targets 可组合
    draft: false,                    // true 仅存草稿不投递
    scheduledAt: '2026-10-01T09:00:00.000+00:00'   // 未来时间即排期发送
});
console.log(message.status, message.deliveredTotal);
// Push:createPush(title / body / data / action / badge / priority 等,按 Android / iOS / Web 平台生效)
// SMS:createSms(content);均有 update*Message(仅 draft 态可改)与 getMessage / listMessages / delete

日志与排查

投递状态与失败原因经消息日志与 deliveryErrors 排查;Client SDK(Web)无此能力面,本卡省略 Web 页签。

const logs = await messaging.listMessageLogs(message.$id);   // 投递日志
const targets = await messaging.listTargets(message.$id);    // topics / users / targets 解析出的收件目标
// status / scheduledAt / deliveredAt / deliveredTotal 可作为消息查询过滤属性
// 通道侧日志:listTopicLogs / listSubscriberLogs / listProviderLogs

示例指引

事实源