novu-trigger-notification

触发通知

通过触发 Novu 工作流发送通知。支持单条、批量、广播和基于主题的发送。

SDK 设置

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

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

单条触发

向一位订阅者发送通知：

const result = await novu.trigger({
  workflowId: "welcome-email",
  to: "subscriber-123",
  payload: {
    userName: "Jane",
    activationLink: "https://app.example.com/activate",
  },
});

通过内联创建订阅者来触发

如果订阅者尚不存在，请提供完整对象 — Novu 会执行 upsert：

const result = await novu.trigger({
  workflowId: "welcome-email",
  to: {
    subscriberId: "user-456",
    email: "[email protected]",
    firstName: "Jane",
    lastName: "Doe",
  },
  payload: { userName: "Jane" },
});

使用事务 ID 触发

使用自定义 transactionId 实现幂等性：

const result = await novu.trigger({
  workflowId: "order-update",
  to: "subscriber-123",
  payload: { orderId: "order-789" },
  transactionId: "unique-tx-id-abc",
});

批量触发

单次请求最多发送 100 个事件：

const result = await novu.triggerBulk({
  events: [
    {
      workflowId: "welcome-email",
      to: "subscriber-1",
      payload: { userName: "Alice" },
    },
    {
      workflowId: "welcome-email",
      to: "subscriber-2",
      payload: { userName: "Bob" },
    },
  ],
});

广播

向环境中的所有订阅者发送：

const result = await novu.triggerBroadcast({
  // here name field is for workflowId
  name: "system-announcement",
  payload: {
    message: "Scheduled maintenance at 2am UTC",
  },
});

基于主题触发

向主题中的所有订阅者发送：

const result = await novu.trigger({
  workflowId: "project-update",
  to: [{
    type: "Topic",
    topicKey: "project-alpha-watchers",
  }],
  payload: { update: "New release deployed" },
});

取消触发

使用 transactionId 取消延迟通知或摘要通知：

await novu.cancel("unique-tx-id-abc");

触发参数

参数	必填	描述
workflowId	是	工作流标识符（不是显示名称）
to	是	订阅者 ID（字符串）、订阅者对象或主题目标
payload	否	传递给工作流的数据，会根据 payloadSchema 进行验证
overrides	否	各渠道的特定提供商覆盖设置
transactionId	否	用于幂等性和取消操作的唯一 ID
actor	否	表示触发操作的人员的订阅者 ID 或对象
context	否	用于多租户 / 组织上下文的键值对

覆盖设置

按触发操作覆盖特定提供商的设置：

const result = await novu.trigger({
  workflowId: "alert",
  to: "subscriber-123",
  payload: { message: "Server down" },
  overrides: {
    "providers": {
      "sendgrid": {
        from: "[email protected]",
        cc: ["[email protected]", "[email protected]"],
        replyTo: "[email protected]",
      }
    }
  },
});

常见问题

1. workflowId 是标识符，不是显示名称 — 请使用定义工作流时设置的标识符，而不是便于阅读的名称。如果未提供，Novu 会自动创建 workflowId
2. 订阅者 upsert — 向不存在的 subscriberId 或字符串形式的 subscriber 对象触发通知时，会使用该 subscriberId 创建订阅者。
3. 批量触发上限为 100 个事件 — 将更大的批次拆分为每组 100 个事件。
4. 取消操作需要 transactionId — 没有它就无法取消触发。请提供自定义 transactionId；如果要稍后取消工作流运行（触发事件），则应存储 Novu 生成的 transactionId。
5. Payload 会根据工作流的 payloadSchema 进行验证 — 如果工作流定义了架构，而 payload 与之不匹配，触发操作就会失败。

参考资料

• 安装与设置
• 单条触发示例
• 批量触发示例
• 主题触发示例
• 最佳实践