novu-manage-subscribers

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Manage Subscribers

管理订阅者

Subscribers are the recipients of your notifications. Each subscriber has a unique

subscriberId

— typically your application's user ID.

订阅者是通知的接收方。每个订阅者都有一个唯一的

subscriberId

——通常是你的应用程序用户ID。

SDK Setup

SDK 设置

typescript

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

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

typescript

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

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

Create a Subscriber

创建订阅者

typescript

await novu.subscribers.create({
  subscriberId: "user-123",       // required — your system's user ID
  email: "jane@example.com",      // 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",
  },
});

Only
subscriberId
is required. All other fields are optional.

typescript

await novu.subscribers.create({
  subscriberId: "user-123",       // 必填项 — 你的系统用户ID
  email: "jane@example.com",      // 可选
  firstName: "Jane",              // 可选
  lastName: "Doe",                // 可选
  phone: "+15551234567",          // 可选
  avatar: "https://example.com/jane.jpg",  // 可选
  locale: "en-US",                // 可选
  timezone: "America/New_York",   // 可选
  data: {                         // 可选 — 自定义键值对数据
    plan: "pro",
    company: "Acme Inc",
  },
});

仅
subscriberId
为必填项。其他所有字段均为可选。

Retrieve a Subscriber

获取订阅者

typescript

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

typescript

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

Search Subscribers

搜索订阅者

typescript

const results = await novu.subscribers.search({
  email: "jane@example.com",
});

typescript

const results = await novu.subscribers.search({
  email: "jane@example.com",
});

Update a Subscriber

更新订阅者

typescript

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

typescript

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

Delete a Subscriber

删除订阅者

typescript

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

typescript

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

Bulk Create

批量创建

Create multiple subscribers at once. 500 subscribers can be created in one request.

typescript

await novu.subscribers.createBulk({
  subscribers: [
    { subscriberId: "user-1", email: "alice@example.com", firstName: "Alice" },
    { subscriberId: "user-2", email: "bob@example.com", firstName: "Bob" },
    { subscriberId: "user-3", email: "carol@example.com", firstName: "Carol" },
  ],
});

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

typescript

await novu.subscribers.createBulk({
  subscribers: [
    { subscriberId: "user-1", email: "alice@example.com", firstName: "Alice" },
    { subscriberId: "user-2", email: "bob@example.com", firstName: "Bob" },
    { subscriberId: "user-3", email: "carol@example.com", firstName: "Carol" },
  ],
});

Topics

主题

Topics are named groups of subscribers. Use them to send notifications to multiple subscribers at once.

主题是命名的订阅者群组。可用于一次性向多个订阅者发送通知。

Create a Topic

创建主题

typescript

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

typescript

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

Add Subscribers to a Topic

为主题添加订阅者

typescript

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

typescript

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

Remove Subscribers from a Topic

从主题中移除订阅者

typescript

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

typescript

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

List Topics

列出主题

typescript

const topics = await novu.topics.list({

});

typescript

const topics = await novu.topics.list({

});

Delete a Topic

删除主题

typescript

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

typescript

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

Trigger to a Topic

向主题触发通知

See trigger-notification for topic trigger examples.

typescript

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

查看trigger-notification获取主题触发示例。

typescript

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

Subscriber Credentials

订阅者凭证

Set channel-specific credentials for push and chat integrations.

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

FCM Push Token

FCM 推送令牌

typescript

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"
);

typescript

await novu.subscribers.credentials.update(
  { 
    providerId: "fcm", 
    //  如果存在多个活跃的fcm类型集成，请使用integrationIdentifier
    integrationIdentifier: "fcm-abc-123", 
    credentials: { deviceTokens: ["fcm-device-token-here"] } 
  },
  "subsriberId-1"
);

APNS Push Token

APNS 推送令牌

typescript

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"
);

typescript

await novu.subscribers.credentials.update(
  { 
    providerId: "apns", 
    // 如果存在多个活跃的apns类型集成，请使用integrationIdentifier
    integrationIdentifier: "fcm-abc-123", 
    credentials: { deviceTokens: ["apns-device-token-here"] } 
  },
  "user-123"
);

Common Pitfalls

常见误区

subscriberId
is YOUR user ID — it bridges your system to Novu. Use a stable, unique identifier from your database.
Subscribers are auto-created on trigger — if you pass a full subscriber object in
```
to
```
when triggering, Novu creates the subscriber if it doesn't exist. But explicit creation gives you more control.
Subscriber data is per-environment — dev, staging, and production have separate subscriber records.
Topics must exist before triggering — create the topic and add subscribers before sending to it.
Deleting a subscriber doesn't delete their notifications — existing notifications remain in the system.
Adding non existent subscriber to topic - if non existent subscriber is added to topic, it is not autocreated in that environment and hence not added to the topic. Always create subscribers before adding into the topic

subscriberId
是你的用户ID——它是你的系统与Novu之间的桥梁。请使用数据库中稳定、唯一的标识符。
订阅者会在触发时自动创建——如果你在触发通知时的
```
to
```
参数中传入完整的订阅者对象，若该订阅者不存在，Novu会自动创建它。但显式创建能让你获得更多控制权。
订阅者数据按环境隔离——开发、预发布和生产环境拥有各自独立的订阅者记录。
触发前必须先创建主题——向主题发送通知前，需先创建主题并添加订阅者。
删除订阅者不会删除其通知——已有的通知仍会保留在系统中。
向主题添加不存在的订阅者——若将不存在的订阅者添加到主题，该订阅者不会在对应环境中自动创建，因此也不会被加入主题。请务必先创建订阅者，再将其添加到主题中。

References

参考资料

Subscriber CRUD Examples
Topics Examples
Credentials Examples

订阅者CRUD示例
主题示例
凭证示例