消息
这是什么 / 何时用
消息发送面:Provider(通道凭据)→ Topic(订阅主题)/ Subscriber(订阅者)→ Message(Email / Push / SMS,支持草稿与排期发送),外加发送 / 通道 / 订阅日志。何时用:公告与通知(邮件 / 短信 / App 推送)、按主题群发、定时投放。
前置
- Server API Key:
messaging.read/messaging.write。 - 至少配置一个可用 Provider(Email 需实例 SMTP 或第三方邮件通道;Push 需 APNs / FCM 凭据;SMS 需 Twilio / Telesign / Vonage / Textmagic 等)。
- 收件人模型:
topics(主题订阅)/users(用户 ID)/targets(用户推送目标 / 邮箱 / 手机号)三类至少其一。
使用骨架
- 配置 Provider:按通道选择创建方法——
createApnsProvider/createFcmProvider(Push)、createMailgunProvider/createResendProvider/createSendgridProvider/createSmtpProvider(Email)、createTwilioProvider/createTelesignProvider/createVonageProvider/createTextmagicProvider(SMS),均配update*Provider/getProvider/listProviders/deleteProvider;凭据字段经 Provider 对应文档核对,secret 类字段保存后不回显。 - 建 Topic:
messaging.createTopic({ topicId, name, subscribeUsers? })(订阅需用户授权时开启);listTopics/getTopic/updateTopic/deleteTopic。 - 订阅者:
messaging.createSubscriber({ topicId, subscriberId, targetId });listSubscribers/getSubscriber/deleteSubscriber。 - 创建消息:按通道选型——
createEmail({ messageId, subject, content, topics?, users?, targets?, cc?, bcc?, attachments?, draft?, html?, scheduledAt? })createPush({ messageId, title?, body?, ... , topics?, users?, targets?, draft?, scheduledAt? })createSms({ messageId, content, ... , draft?, scheduledAt? })- 均有
updateEmail/updatePush/updateSms与getMessage/listMessages/delete。
- 草稿与排期:
draft: true仅保存不发送(草稿态,可反复 update);scheduledAt填未来 ISO 8601 时间即排期发送;两者可组合(草稿 + 未来发送时间)。到点由平台投递,不需要调用方轮询触发。 - 日志与排查:
listMessageLogs(投递状态、scheduledAt/deliveredAt/deliveredTotal/status可作为查询过滤属性)、listTopicLogs/listSubscriberLogs/listProviderLogs;messaging.listTargets查用户的推送目标。
关键参数与返回
| 调用 | 关键参数 | 返回 |
|---|---|---|
createTopic | topicId、name、subscribeUsers?(是否要求用户授权订阅) | Models.Topic |
createSubscriber | topicId、subscriberId、targetId | Models.Subscriber |
createEmail | messageId、subject、content、topics?/users?/targets?、cc?/bcc?/attachments?、draft?、html?、scheduledAt? | Models.Message(含 status、scheduledAt、deliveredTotal) |
createPush / createSms | messageId、内容字段、投递目标、draft?、scheduledAt? | Models.Message |
create*Provider | 通道凭据(providerId、name、auth 字段、enabled 等) | Provider(secret 不回显) |
消息查询支持按 scheduledAt、deliveredAt、deliveredTotal、status、description、providerType 属性过滤(queries 上限 100 条)。
错误与边界
- 没有可用 Provider / 凭据错误:消息停在待投递并记录失败原因——先查
listMessageLogs与 Provider 配置。 scheduledAt必须是未来时间;修改排期用update*Message系列更新同messageId。draft: true的消息不会投递;忘记改草稿态是「为什么不发」的头号原因。- 投递目标三类(topics / users / targets)可组合;
targets指向用户的推送目标(users.createTarget或messaging.listTargets里的 ID)。 - Email 附件引用项目内文件 ID;大小与格式受 Provider 与实例限制。
- 订阅类 Topic 开启
subscribeUsers时,订阅操作需目标用户授权链路(用户 Session 或服务端代操作)。
SDK 类别差异
- Server SDK:本页主体(Provider / Topic / Subscriber / Message 全管理 + 日志);Java 同形同步方法,Python snake_case 同构。
- Client SDK:不提供消息发送管理;用户侧只有推送目标注册(profile.md)与 Realtime 订阅(client-sdk/web.md)。
- Console SDK:项目设置里的 Email / SMS 模板与 SMTP 测试(
updateEmailTemplate、createSmtpTest等)属控制面配置,与业务发送分工不同。 - 差异入口:server-sdk/nodejs.md。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
配置 Provider
消息发送面仅服务端暴露,Client SDK(Web)无此能力面,本卡省略 Web 页签。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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 重传import io.agentbase.ID;
import io.agentbase.services.Messaging;
Messaging messaging = new Messaging(client); // client 初始化见 server-sdk/java.md
messaging.createFcmProvider(ID.unique(), "app-push",
java.util.Map.of("type", "service_account", "project_id", "my-project"), // serviceAccountJSON
true); // enabled
// 11 种通道 create*Provider(apns / fcm / mailgun / msg91 / resend / sendgrid / smtp / telesign /
// textmagic / twilio / vonage),均配 update*Provider / getProvider / listProviders / deleteProvider
// (位置参数);createSmtpProvider 多一个必填 host:(providerId, name, host, port, ...)
// secret 类凭据保存后不回显,轮换经 update*Provider 重传from agentbase.id import ID
from agentbase.services.messaging import Messaging
messaging = Messaging(client) # client 初始化见 server-sdk/python.md
messaging.create_fcm_provider(
provider_id=ID.unique(),
name='app-push',
service_account_json={'type': 'service_account', 'project_id': 'my-project'}, # FCM 服务账号 JSON
enabled=True)
# Email:create_mailgun_provider / create_resend_provider / create_sendgrid_provider / create_smtp_provider
# SMS:create_twilio_provider / create_telesign_provider / create_vonage_provider / create_textmagic_provider
# 均配 update_*_provider / get_provider / list_providers / delete_provider;secret 类凭据保存后不回显messaging := agentbase.NewMessaging(cl) // facade 构造器;cl 为已装载 API Key 的 Client
_, err := messaging.CreateFcmProvider(id.Unique(), "app-push",
messaging.WithCreateFcmProviderServiceAccountJSON(
map[string]interface{}{"type": "service_account", "project_id": "my-project"}),
messaging.WithCreateFcmProviderEnabled(true))
// Email:CreateMailgunProvider / CreateResendProvider / CreateSendgridProvider / CreateSmtpProvider
// SMS:CreateTwilioProvider / CreateTelesignProvider / CreateVonageProvider / CreateTextmagicProvider
// 均配 Update*Provider / GetProvider / ListProviders / DeleteProvider;secret 类凭据保存后不回显curl -sS -X POST "$APPBASE_ENDPOINT/messaging/providers/fcm" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"providerId":"app-push","name":"App Push","serviceAccountJSON":{"type":"service_account","project_id":"my-project"},"enabled":true}'
# 其余通道:POST /messaging/providers/{apns|mailgun|resend|sendgrid|smtp|twilio|vonage|telesign|msg91|textmagic}
# 更新:PATCH /messaging/providers/{type}/{providerId}(未提供的字段保留现值);凭证不回显明文
# 删除 provider 会让未发送消息投递失败:DELETE /messaging/providers/{providerId}建 Topic
subscribe 控制哪些角色可订阅(缺省全部用户);Client SDK(Web)无此能力面,本卡省略 Web 页签。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
const topic = await messaging.createTopic({
topicId: ID.unique(),
name: 'product-announcements',
subscribe: ['users'] // 可订阅角色数组,最多 100 个
});
await messaging.listTopics();
await messaging.getTopic(topic.$id);
// updateTopic:调整名称与可订阅角色;deleteTopic:删除主题并级联删除订阅关系import io.agentbase.ID;
import io.agentbase.services.Messaging;
Messaging messaging = new Messaging(client); // client 初始化见 server-sdk/java.md
var topic = messaging.createTopic(ID.unique(), "product-announcements",
java.util.List.of("users")); // 可订阅角色数组,最多 100 个
messaging.listTopics(null, null, null); // queries / search / total
messaging.getTopic(topic.getId());
// updateTopic(topicId, name, subscribe):调整名称与可订阅角色
// deleteTopic(topicId):删除主题并级联删除订阅关系messaging = Messaging(client) # client 初始化见 server-sdk/python.md
topic = messaging.create_topic(topic_id=ID.unique(), name='product-announcements',
subscribe=['users']) # 可订阅角色数组,最多 100 个
messaging.list_topics()
messaging.get_topic(topic['$id'])
# update_topic:调整名称与可订阅角色;delete_topic:删除主题并级联删除订阅关系topic, err := messaging.CreateTopic(id.Unique(), "product-announcements",
messaging.WithCreateTopicSubscribe([]string{"users"})) // 可订阅角色数组,最多 100 个
_, err = messaging.ListTopics()
_, err = messaging.GetTopic(topic.Id)
// UpdateTopic:调整名称与可订阅角色;DeleteTopic:删除主题并级联删除订阅关系curl -sS -X POST "$APPBASE_ENDPOINT/messaging/topics" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"topicId":"product-announcements","name":"Product Announcements","subscribe":["users"]}'
# 列表(可过滤 name / description / emailTotal / smsTotal / pushTotal):GET /messaging/topics
# 更新:PATCH /messaging/topics/{topicId}(name + subscribe);删除(级联删订阅):DELETE /messaging/topics/{topicId}订阅者
targetId 必须来自已存在用户的消息目标;Client SDK(Web)无此能力面,本卡省略 Web 页签。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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); // 退订var subscriber = messaging.createSubscriber(topic.getId(), ID.unique(),
"<targetId>"); // 用户的消息目标(users.createTarget 或 messaging.listTargets)
messaging.listSubscribers(topic.getId(), null, null, null); // queries / search / total
messaging.getSubscriber(topic.getId(), subscriber.getId());
messaging.deleteSubscriber(topic.getId(), subscriber.getId()); // 退订subscriber = messaging.create_subscriber(
topic_id=topic['$id'],
subscriber_id=ID.unique(),
target_id='<targetId>') # 用户的消息目标(users.create_target 或 messaging.list_targets)
messaging.list_subscribers(topic_id=topic['$id'])
messaging.get_subscriber(topic_id=topic['$id'], subscriber_id=subscriber['$id'])
messaging.delete_subscriber(topic_id=topic['$id'], subscriber_id=subscriber['$id']) # 退订subscriber, err := messaging.CreateSubscriber(topic.Id, id.Unique(), "<targetId>") // targetId:用户的消息目标
_, err = messaging.ListSubscribers(topic.Id)
_, err = messaging.GetSubscriber(topic.Id, subscriber.Id)
_, err = messaging.DeleteSubscriber(topic.Id, subscriber.Id) // 退订curl -sS -X POST "$APPBASE_ENDPOINT/messaging/topics/product-announcements/subscribers" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"subscriberId":"sub-001","targetId":"66f1a2b3c4d5e6f7"}'
# 列表:GET /messaging/topics/{topicId}/subscribers;单条:GET …/subscribers/{subscriberId}
# 退订:DELETE /messaging/topics/{topicId}/subscribers/{subscriberId}创建消息(草稿与排期)
draft: true 仅保存不投递、可反复 update 后再发;scheduledAt 填未来 ISO 8601 时间即排期,到点由平台投递。Client SDK(Web)无此能力面,本卡省略 Web 页签。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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 / deletevar message = messaging.createEmail(ID.unique(), "10 月产品更新", "<h1>10 月产品更新</h1>",
java.util.List.of(topic.getId()), // topics;投递目标 topics / users / targets 可组合
null, null, null, null, null, // users / targets / cc / bcc / attachments
false, true, // draft(true 仅存草稿不投递)、html
"2026-10-01T09:00:00.000+00:00"); // scheduledAt:未来时间即排期发送
System.out.println(message.getStatus() + " " + message.getDeliveredTotal());
// Push:createPush(messageId, title, body, topics, …, badge, draft, scheduledAt, …) 全位置参数可选传
// SMS:createSms(messageId, content, …);均有 updateEmail / updatePush / updateSms(仅 draft 态可改)
// 与 getMessage / listMessages / deletemessage = messaging.create_email(
message_id=ID.unique(),
subject='10 月产品更新',
content='<h1>10 月产品更新</h1>',
html=True,
topics=[topic['$id']], # 投递目标 topics / users / targets 可组合
draft=False, # True 仅存草稿不投递
scheduled_at='2026-10-01T09:00:00+00:00') # 未来时间即排期发送
print(message.status) # scheduledAt / deliveredTotal 随返回模型可查
# Push:create_push(title / body / data / action / badge / priority 等,按 Android / iOS / Web 平台生效)
# SMS:create_sms(content);均有 update_email / update_push / update_sms(仅 draft 态可改)与
# get_message / list_messages / deletemessage, err := messaging.CreateEmail(id.Unique(), "10 月产品更新", "<h1>10 月产品更新</h1>",
messaging.WithCreateEmailHtml(true),
messaging.WithCreateEmailTopics([]string{topic.Id}), // 投递目标 topics / users / targets 可组合
messaging.WithCreateEmailDraft(false), // true 仅存草稿不投递
messaging.WithCreateEmailScheduledAt("2026-10-01T09:00:00.000+00:00")) // 未来时间即排期发送
// message.Status / ScheduledAt / DeliveredTotal 随返回模型可查
// Push:CreatePush(title / body / data / action / badge / priority 等,按 Android / iOS / Web 平台生效)
// SMS:CreateSms(content);均有 UpdateEmail / UpdatePush / UpdateSms(仅 draft 态可改)与
// GetMessage / ListMessages / Deletecurl -sS -X POST "$APPBASE_ENDPOINT/messaging/messages/email" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"messageId":"oct-newsletter","subject":"10 月产品更新","content":"<h1>10 月产品更新</h1>","html":true,"topics":["product-announcements"],"draft":false,"scheduledAt":"2026-10-01T09:00:00.000+00:00"}'
# 附件为复合 ID:attachments:["<BUCKET_ID>:<FILE_ID>"](文件须已在 Storage 上传)
# Push / SMS:POST /messaging/messages/push、/messaging/messages/sms(sms 端点 spec 标记 deprecated,2.6.0 仍可用)
# 更新仅 draft 态可改:PATCH /messaging/messages/email/{messageId}日志与排查
投递状态与失败原因经消息日志与 deliveryErrors 排查;Client SDK(Web)无此能力面,本卡省略 Web 页签。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
const logs = await messaging.listMessageLogs(message.$id); // 投递日志
const targets = await messaging.listTargets(message.$id); // topics / users / targets 解析出的收件目标
// status / scheduledAt / deliveredAt / deliveredTotal 可作为消息查询过滤属性
// 通道侧日志:listTopicLogs / listSubscriberLogs / listProviderLogsmessaging.listMessageLogs(message.getId(), null, null); // 投递日志;queries / total
messaging.listTargets(message.getId(), null, null); // topics / users / targets 解析出的收件目标
// status / scheduledAt / deliveredAt / deliveredTotal 可作为消息查询过滤属性
// 通道侧日志:listTopicLogs(topicId, queries, total) / listSubscriberLogs(subscriberId, queries, total)
// / listProviderLogs(providerId, queries, total)messaging.list_message_logs(message_id=message['$id']) # 投递日志
messaging.list_targets(message_id=message['$id']) # topics / users / targets 解析出的收件目标
# status / scheduledAt / deliveredAt / deliveredTotal 可作为消息查询过滤属性
# 通道侧日志:list_topic_logs / list_subscriber_logs / list_provider_logs_, err := messaging.ListMessageLogs(message.Id) // 投递日志
_, err = messaging.ListTargets(message.Id) // topics / users / targets 解析出的收件目标
// status / scheduledAt / deliveredAt / deliveredTotal 可作为消息查询过滤属性
// 通道侧日志:ListTopicLogs / ListSubscriberLogs / ListProviderLogscurl -sS -G "$APPBASE_ENDPOINT/messaging/messages/oct-newsletter/logs" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
--data-urlencode "queries[]=limit(25)"
# 解析出的收件目标:GET /messaging/messages/{messageId}/targets
# 主题 / 订阅者 / 提供商日志:GET /messaging/topics/{topicId}/logs、/messaging/subscribers/{subscriberId}/logs、/messaging/providers/{providerId}/logs(仅 limit / offset 分页)
# 消息停在待投递先查通道:GET /messaging/providers示例指引
- 各语言写法集中在语言树
examples/;Provider 类型清单与模块总览见skills/ob-agentbase/references/server-sdks/java.md、skills/ob-agentbase/references/server-sdks/nodejs.md。
事实源
skills/ob-agentbase/references/server-sdks/java.md(模块总览)skills/ob-agentbase/references/server-sdks/nodejs.md- appbase v2.7.0(tag v2.7.0)
- agentbase-sdks v2.7.0 specs(
messagingservice 面:topics / subscribers / messages / providers / logs 与draft、scheduledAt参数)