novu-trigger-notification

通知のトリガー

Novu のワークフローをトリガーして通知を送信します。個別、バルク、一斉配信、トピックベースの配信に対応しています。

SDK のセットアップ

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

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

個別のトリガー

1 人のサブスクライバーに通知を送信します。

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

サブスクライバーをその場で作成してトリガー

サブスクライバーがまだ存在しない場合は、完全なオブジェクトを指定します。Novu がサブスクライバーをアップサートします。

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

バルクトリガー

1 回のリクエストで最大 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. サブスクライバーのアップサート — 存在しない subscriberId または文字列の subscriber オブジェクトを宛先としてトリガーすると、その subscriberId を持つサブスクライバーが作成されます。
3. バルクトリガーの上限は 100 件のイベントです — それより大きいバッチは、100 件ずつに分割してください。
4. キャンセルには transactionId が必要です — これがないとトリガーをキャンセルできません。カスタムの transactionId を指定するか、後でワークフローの実行（トリガーイベント）をキャンセルする場合は、Novu が生成した transactionId を保存してください。
5. ペイロードはワークフローの payloadSchema に照らして検証されます — ワークフローでスキーマが定義されている場合、ペイロードが一致しないとトリガーは失敗します。

参考資料

• インストールとセットアップ
• 個別トリガーの例
• バルクトリガーの例
• トピックトリガーの例
• ベストプラクティス