Back to Details

novu-trigger-notification

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Trigger Notification

触发通知

Send notifications by triggering Novu workflows. Supports single, bulk, broadcast, and topic-based delivery.
通过触发Novu工作流发送通知。支持单次、批量、广播及基于主题的投递方式。

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,
});

Single Trigger

单次触发

Send a notification to one subscriber:
typescript
const result = await novu.trigger({
  workflowId: "welcome-email",
  to: "subscriber-123",
  payload: {
    userName: "Jane",
    activationLink: "https://app.example.com/activate",
  },
});
向单个订阅者发送通知：
typescript
const result = await novu.trigger({
  workflowId: "welcome-email",
  to: "subscriber-123",
  payload: {
    userName: "Jane",
    activationLink: "https://app.example.com/activate",
  },
});

Trigger with Inline Subscriber Creation

内联创建订阅者并触发

If the subscriber doesn't exist yet, provide the full object — Novu upserts the subscriber:
typescript
const result = await novu.trigger({
  workflowId: "welcome-email",
  to: {
    subscriberId: "user-456",
    email: "jane@example.com",
    firstName: "Jane",
    lastName: "Doe",
  },
  payload: { userName: "Jane" },
});
如果订阅者尚未存在，提供完整对象即可——Novu会自动创建或更新该订阅者：
typescript
const result = await novu.trigger({
  workflowId: "welcome-email",
  to: {
    subscriberId: "user-456",
    email: "jane@example.com",
    firstName: "Jane",
    lastName: "Doe",
  },
  payload: { userName: "Jane" },
});

Trigger with Transaction ID

使用事务ID触发

Use custom 
transactionId
for idempotency:
typescript
const result = await novu.trigger({
  workflowId: "order-update",
  to: "subscriber-123",
  payload: { orderId: "order-789" },
  transactionId: "unique-tx-id-abc",
});
使用自定义
transactionId
实现幂等性：
typescript
const result = await novu.trigger({
  workflowId: "order-update",
  to: "subscriber-123",
  payload: { orderId: "order-789" },
  transactionId: "unique-tx-id-abc",
});

Bulk Trigger

批量触发

Send up to 100 events in a single request:
typescript
const result = await novu.triggerBulk({
  events: [
    {
      workflowId: "welcome-email",
      to: "subscriber-1",
      payload: { userName: "Alice" },
    },
    {
      workflowId: "welcome-email",
      to: "subscriber-2",
      payload: { userName: "Bob" },
    },
  ],
});
单次请求最多可发送100个事件：
typescript
const result = await novu.triggerBulk({
  events: [
    {
      workflowId: "welcome-email",
      to: "subscriber-1",
      payload: { userName: "Alice" },
    },
    {
      workflowId: "welcome-email",
      to: "subscriber-2",
      payload: { userName: "Bob" },
    },
  ],
});

Broadcast

广播

Send to all subscribers in the environment:
typescript
const result = await novu.triggerBroadcast({
  // here name field is for workflowId
  name: "system-announcement",
  payload: {
    message: "Scheduled maintenance at 2am UTC",
  },
});
向当前环境中的所有订阅者发送通知：
typescript
const result = await novu.triggerBroadcast({
  // 此处name字段对应workflowId
  name: "system-announcement",
  payload: {
    message: "Scheduled maintenance at 2am UTC",
  },
});

Topic-Based Trigger

基于主题的触发

Send to all subscribers in a topic:
typescript
const result = await novu.trigger({
  workflowId: "project-update",
  to: [{
    type: "Topic",
    topicKey: "project-alpha-watchers",
  }],
  payload: { update: "New release deployed" },
});
向某一主题下的所有订阅者发送通知：
typescript
const result = await novu.trigger({
  workflowId: "project-update",
  to: [{
    type: "Topic",
    topicKey: "project-alpha-watchers",
  }],
  payload: { update: "New release deployed" },
});

Cancel a Trigger

取消触发

Cancel delayed or digested notifications using the 
transactionId
:
typescript
await novu.cancel("unique-tx-id-abc");
使用
transactionId
取消延迟或待处理的通知：
typescript
await novu.cancel("unique-tx-id-abc");

Trigger Parameters

触发参数

ParameterRequiredDescription
workflowId
YesThe workflow identifier (not display name)
to
YesSubscriber ID (string), subscriber object, or topic target
payload
NoData passed to the workflow, validated against 
payloadSchema
overrides
NoProvider-specific overrides per channel
transactionId
NoUnique ID for idempotency and cancellation
actor
NoSubscriber ID or object representing who triggered the action
context
NoKey-value pairs for multi-tenancy / organizational context
参数是否必填描述
workflowId
是工作流标识符（非显示名称）
to
是订阅者ID（字符串）、订阅者对象或主题目标
payload
否传递给工作流的数据，会根据
payloadSchema
进行验证
overrides
否针对各渠道的服务商特定配置覆盖
transactionId
否用于幂等性和取消操作的唯一ID
actor
否代表触发操作发起者的订阅者ID或对象
context
否用于多租户/组织上下文的键值对

Overrides

配置覆盖

Override provider-specific settings per trigger:
typescript
const result = await novu.trigger({
  workflowId: "alert",
  to: "subscriber-123",
  payload: { message: "Server down" },
  overrides: {
    "providers": {
      "sendgrid": {
        from: "alerts@example.com",
        cc: ["user1@example.com", "user2@example.com"],
        replyTo: "support@example.com",
      }
    }
  },
});
在每次触发时覆盖服务商特定配置：
typescript
const result = await novu.trigger({
  workflowId: "alert",
  to: "subscriber-123",
  payload: { message: "Server down" },
  overrides: {
    "providers": {
      "sendgrid": {
        from: "alerts@example.com",
        cc: ["user1@example.com", "user2@example.com"],
        replyTo: "support@example.com",
      }
    }
  },
});

Common Pitfalls

常见误区

  1. workflowId
    is the identifier, not the display name     — use the identifier you set when defining the workflow, not its human-readable name. Novu creates workflowId automatically if not provided
  2. Subscriber upsert — triggering to a non-existent 
    subscriberId
    or 
    subscriber
    object string will create the subscriber with that subscriberId.
  3. Bulk trigger limit is 100 events — chunk larger batches into groups of 100.
  4. transactionId
    is required for cancellation     — you cannot cancel a trigger without it. Either provide custom transactionId or store novu generated transactionId if usecase is to cancel the workflow run (trigger event) later.
  5. Payload is validated against the workflow's 
    payloadSchema
     — if the workflow defines a schema, the trigger will fail if the payload doesn't match.
  1. workflowId
    是标识符而非显示名称     — 使用定义工作流时设置的标识符，而非其易读名称。若未手动设置，Novu会自动生成workflowId
  2. 订阅者自动创建/更新 — 向不存在的
    subscriberId
    或订阅者对象字符串触发通知时，会自动创建该订阅者并使用对应的subscriberId
  3. 批量触发上限为100个事件 — 若批量事件超过100个，需拆分为多个100组的批次
  4. 取消操作需要
    transactionId
     — 没有该ID无法取消触发。如果后续需要取消工作流运行（触发事件），请自行提供自定义transactionId或存储Novu生成的transactionId
  5. Payload会根据工作流的
    payloadSchema
    验证     — 如果工作流定义了schema，当payload不符合时触发会失败

References

参考链接

  • Installation & Setup
  • Single Trigger Examples
  • Bulk Trigger Examples
  • Topic Trigger Examples
  • Best Practices
  • 安装与设置
  • 单次触发示例
  • 批量触发示例
  • 主题触发示例
  • 最佳实践