Docs
文档目录

消息

这是什么 / 何时用

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

前置

使用骨架

  1. 配置 Provider:按通道选择创建方法——createApnsProvider / createFcmProvider(Push)、createMailgunProvider / createResendProvider / createSendgridProvider / createSmtpProvider(Email)、createTwilioProvider / createTelesignProvider / createVonageProvider / createTextmagicProvider(SMS),均配 update*Provider / getProvider / listProviders / deleteProvider;凭据字段经 Provider 对应文档核对,响应可能包含敏感配置,请避免记录或泄露。

  2. 建 Topic:messaging.createTopic({ topicId, name, subscribeUsers })(subscribeUsers 可选)(订阅需用户授权时开启);listTopics / getTopic / updateTopic / deleteTopic。

  3. 订阅者:messaging.createSubscriber({ topicId, subscriberId, targetId });listSubscribers / getSubscriber / deleteSubscriber。

  4. 创建消息:按通道选型——

    • createEmail({ messageId, subject, content, topics, users, targets, cc, bcc, attachments, draft, html, scheduledAt })(topics、users、targets、cc、bcc、attachments、draft、html、scheduledAt 均可选)

    • createPush({ messageId, title, body, ... , topics, users, targets, draft, scheduledAt })(title、body、topics、users、targets、draft、scheduledAt 均可选)

    • createSms({ messageId, content, ... , draft, scheduledAt })(draft、scheduledAt 均可选)

    • 均有 updateEmail / updatePush / updateSms 与 getMessage / listMessages / delete。

  5. 草稿与排期:draft: true 仅保存不发送(草稿态,可反复 update);scheduledAt 填未来 ISO 8601 时间即排期发送;两者可组合(草稿 + 未来发送时间)。到点由平台投递,不需要调用方轮询触发。

  6. 日志与排查:listMessageLogs(投递状态、scheduledAt / deliveredAt / deliveredTotal / status 可作为查询过滤属性)、listTopicLogs / listSubscriberLogs / listProviderLogs;messaging.listTargets 查用户的推送目标。

关键参数与返回

调用关键参数返回
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(响应可能包含敏感配置)

消息查询支持按 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
// 响应可能包含敏感配置,轮换经 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

示例指引