novu-manage-subscribers

管理订阅者

订阅者是通知的接收者。每位订阅者都有唯一的 subscriberId，通常是你应用的用户 ID。

SDK 设置

import { Novu } from "@novu/api";

const novu = new Novu({
  secretKey: process.env.NOVU_SECRET_KEY,
});

创建订阅者

await novu.subscribers.create({
  subscriberId: "user-123",       // required — your system's user ID
  email: "[email protected]",      // optional
  firstName: "Jane",              // optional
  lastName: "Doe",                // optional
  phone: "+15551234567",          // optional
  avatar: "https://example.com/jane.jpg",  // optional
  locale: "en-US",                // optional
  timezone: "America/New_York",   // optional
  data: {                         // optional — custom key-value data
    plan: "pro",
    company: "Acme Inc",
  },
});

只需要 subscriberId。 其他字段均为可选项。

检索订阅者

const subscriber = await novu.subscribers.retrieve("user-123");

搜索订阅者

const results = await novu.subscribers.search({
  email: "[email protected]",
});

更新订阅者

await novu.subscribers.patch(
  { firstName: "Jane", data: { plan: "enterprise" } },
  // subscriberId
  "user-123"
);

删除订阅者

await novu.subscribers.delete("user-123");

批量创建

一次创建多个订阅者。单个请求最多可创建 500 位订阅者。

await novu.subscribers.createBulk({
  subscribers: [
    { subscriberId: "user-1", email: "[email protected]", firstName: "Alice" },
    { subscriberId: "user-2", email: "[email protected]", firstName: "Bob" },
    { subscriberId: "user-3", email: "[email protected]", firstName: "Carol" },
  ],
});

主题

主题是订阅者的命名分组。你可以使用主题一次向多位订阅者发送通知。

创建主题

await novu.topics.create({
  key: "engineering-team",
  name: "Engineering Team",
});

向主题添加订阅者

await novu.topics.subscriptions.create(
  { subscriptions: ["subscriberId-1", "subscriberId-2", "subscriberId-3"] },
  "engineering-team-topic"
);

从主题移除订阅者

await novu.topics.subscriptions.delete(
  { subscriptions: ["subscriberId-1", "subscriberId-2"] },
  "engineering-team-topic"
);

列出主题

const topics = await novu.topics.list({

});

删除主题

await novu.topics.delete("engineering-team-topic");

向主题触发通知

请参阅 trigger-notification 中的主题触发示例。

await novu.trigger({
  workflowId: "project-update",
  to: { type: "Topic", topicKey: "engineering-team-topic" },
  payload: { message: "Sprint review at 3pm" },
});

订阅者凭据

为推送和聊天集成设置特定渠道的凭据。

FCM 推送令牌

await novu.subscribers.credentials.update(
  { 
    providerId: "fcm", 
    //  use integrationIdentifier if there are multiple fcm type active integrations
    integrationIdentifier: "fcm-abc-123", 
    credentials: { deviceTokens: ["fcm-device-token-here"] } 
  },
  "subsriberId-1"
);

APNS 推送令牌

await novu.subscribers.credentials.update(
  { 
    providerId: "apns", 
    // use integrationIdentifier if there are multiple apns type active integrations
    integrationIdentifier: "fcm-abc-123", 
    credentials: { deviceTokens: ["apns-device-token-here"] } 
  },
  "user-123"
);

常见问题

1. subscriberId 是你的用户 ID——它将你的系统与 Novu 连接起来。请使用数据库中稳定且唯一的标识符。
2. 触发通知时会自动创建订阅者——如果触发通知时在 to 中传入完整的订阅者对象，而该订阅者尚不存在，Novu 就会创建它。不过，显式创建订阅者能让你拥有更多控制权。
3. 订阅者数据按环境隔离——开发、预发布和生产环境中的订阅者记录彼此独立。
4. 触发通知前必须先创建主题——发送通知前，请先创建主题并添加订阅者。
5. 删除订阅者不会删除其通知——现有通知会保留在系统中。
6. 将不存在的订阅者添加到主题 - 如果将不存在的订阅者添加到主题，该订阅者不会在对应环境中自动创建，因此也不会被添加到主题。请始终先创建订阅者，再将其添加到主题。

参考资料

• 订阅者 CRUD 示例
• 主题示例
• 凭据示例