Docs
Contents

Messaging

Overview and use cases

Messaging surface: Provider (channel credentials) → Topic (subscription topic) / Subscriber (subscriber) → Message (Email / Push / SMS, supporting drafts and scheduled sending), plus send / channel / subscription logs. Use cases: announcements and notifications (email / SMS / app push), topic-based bulk sending, scheduled delivery.

Prerequisites

Usage workflow

  1. Configure a Provider: choose the creation method by channel — createApnsProvider / createFcmProvider (Push), createMailgunProvider / createResendProvider / createSendgridProvider / createSmtpProvider (Email), createTwilioProvider / createTelesignProvider / createVonageProvider / createTextmagicProvider (SMS), all with update*Provider / getProvider / listProviders / deleteProvider; verify credential fields against the corresponding Provider documentation; responses may contain sensitive configuration; avoid logging or exposing it.

  2. Create a Topic: messaging.createTopic({ topicId, name, subscribeUsers }) (subscribeUsers optional) (enable when subscription requires user authorization); listTopics / getTopic / updateTopic / deleteTopic.

  3. Subscribers: messaging.createSubscriber({ topicId, subscriberId, targetId }); listSubscribers / getSubscriber / deleteSubscriber.

  4. Create a message: choose by channel —

    • createEmail({ messageId, subject, content, topics, users, targets, cc, bcc, attachments, draft, html, scheduledAt }) (topics, users, targets, cc, bcc, attachments, draft, html, scheduledAt all optional)

    • createPush({ messageId, title, body, ... , topics, users, targets, draft, scheduledAt }) (title, body, topics, users, targets, draft, scheduledAt all optional)

    • createSms({ messageId, content, ... , draft, scheduledAt }) (draft, scheduledAt both optional)

    • All have updateEmail / updatePush / updateSms and getMessage / listMessages / delete.

  5. Drafts and scheduling: draft: true only saves without sending (draft state, can be updated repeatedly); scheduledAt with a future ISO 8601 time schedules sending; the two can be combined (draft + future send time). The platform delivers at the scheduled time; the caller does not need to poll to trigger it.

  6. Logs and troubleshooting: listMessageLogs (delivery status; scheduledAt / deliveredAt / deliveredTotal / status can be used as query filter attributes), listTopicLogs / listSubscriberLogs / listProviderLogs; messaging.listTargets to look up a user's push targets.

Key parameters and returns

CallKey parametersReturns
createTopictopicId, name, subscribeUsers (optional; whether user authorization is required to subscribe)Models.Topic
createSubscribertopicId、subscriberId、targetIdModels.Subscriber
createEmailmessageId, subject, content, topics / users / targets (all optional), cc / bcc / attachments (all optional), draft (optional), html (optional), scheduledAt (optional)Models.Message (including status, scheduledAt, deliveredTotal)
createPush / createSmscontent fields, delivery targets, messageId (optional), draft (optional), scheduledAt (optional)Models.Message
create*ProviderChannel credentials (providerId, name, auth fields, enabled, etc.)Provider (response may contain sensitive configuration)

Message queries support filtering by the scheduledAt, deliveredAt, deliveredTotal, status, description, providerType attributes (queries limit 100 records).

Errors and boundaries

SDK Category Differences

Examples by language

The following provides examples by language, item by item along the usage workflow; each card can switch languages (synced across the page).

Configure a Provider

The messaging surface is exposed only server-side; the Client SDK (Web) has no such capability surface, so this card omits the Web tab.

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

const messaging = new Messaging(client);   // For client initialization, see 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 additionally has createApnsProvider; all pair with update*Provider / getProvider / listProviders / deleteProvider
// responses may contain sensitive configuration; rotate credentials via update*Provider

Create a Topic

subscribe controls which roles can subscribe (defaults to all users); the Client SDK (Web) has no such capability surface, so this card omits the Web tab.

const topic = await messaging.createTopic({
    topicId: ID.unique(),
    name: 'product-announcements',
    subscribe: ['users']   // An array of roles can be subscribed, up to 100
});

await messaging.listTopics();
await messaging.getTopic(topic.$id);
// updateTopic: adjust the name and subscribable roles; deleteTopic: delete the topic and cascade-delete subscriptions

Subscribers

targetId must come from an existing user's message targets; the Client SDK (Web) has no such capability surface, so this card omits the Web tab.

const subscriber = await messaging.createSubscriber({
    topicId: topic.$id,
    subscriberId: ID.unique(),
    targetId: '<targetId>'   // The user's message target (users.createTarget or messaging.listTargets)
});

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

Create a message (drafts and scheduling)

draft: true only saves without delivering and can be updated repeatedly before sending; scheduledAt with a future ISO 8601 time schedules delivery, and the platform delivers at that time. The Client SDK (Web) has no such capability surface, so this card omits the Web tab.

const message = await messaging.createEmail({
    messageId: ID.unique(),
    subject: '10 月产品更新',
    content: '<h1>10 月产品更新</h1>',
    html: true,
    topics: [topic.$id],             // Delivery targets topics / users / targets are composable
    draft: false,                    // true only stores the draft without delivering it
    scheduledAt: '2026-10-01T09:00:00.000+00:00'   // A future time means scheduled sending
});
console.log(message.status, message.deliveredTotal);
// Push: createPush (title / body / data / action / badge / priority etc., effective per Android / iOS / Web platform)
// SMS: createSms (content); both have update*Message (only editable in draft state) and getMessage / listMessages / delete

Logs and troubleshooting

Delivery status and failure reasons are investigated via message logs and deliveryErrors; the Client SDK (Web) has no such capability surface, so this card omits the Web tab.

const logs = await messaging.listMessageLogs(message.$id);   // Delivery logs
const targets = await messaging.listTargets(message.$id);    // recipient targets resolved from topics / users / targets
// status / scheduledAt / deliveredAt / deliveredTotal can be used as query filter attributes for messages
// Channel-side logs: listTopicLogs / listSubscriberLogs / listProviderLogs

Example Guide