Agent Skills › novuhq/novu › novu-trigger-notification

novu-trigger-notification

GitHub

该 Skill 用于触发 Novu 通知工作流，支持单条、批量、广播及基于主题的多种消息发送方式。适用于交易性通知、系统告警或事件驱动的消息推送场景。

docs/.mintlify/skills/trigger-notification/SKILL.md novuhq/novu

Trigger Scenarios

需要发送电子邮件、短信、推送等通知时执行批量通知或全量广播任务时通过主题向特定用户组发送消息时

Install

npx skills add novuhq/novu --skill novu-trigger-notification -g -y

More Options

Non-standard path

npx skills add https://github.com/novuhq/novu/tree/next/docs/.mintlify/skills/trigger-notification -g -y

Use without installing

npx skills use novuhq/novu@novu-trigger-notification

指定 Agent (Claude Code)

npx skills add novuhq/novu --skill novu-trigger-notification -a claude-code -g -y

安装 repo 全部 skill

npx skills add novuhq/novu --all -g -y

预览 repo 内 skill

npx skills add novuhq/novu --list

SKILL.md

Frontmatter

{
    "name": "novu-trigger-notification",
    "inputs": [
        {
            "name": "NOVU_SECRET_KEY",
            "type": "secret",
            "required": true,
            "description": "Server-side API key from https:\/\/dashboard.novu.co\/api-keys. Used by @novu\/api."
        }
    ],
    "description": "Trigger Novu notification workflows to send messages across email, SMS, push, chat, and in-app channels. Supports single triggers, bulk triggers, broadcast to all subscribers, topic-based targeting, and cancellation. Use when sending transactional notifications, alerts, or any event-driven messages."
}

Trigger Notification

Send notifications by triggering Novu workflows. Supports single, bulk, broadcast, and topic-based delivery.

SDK Setup

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

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

Single Trigger

Send a notification to one subscriber:

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:

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

Use custom transactionId for idempotency:

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:

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:

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

Topic-Based Trigger

Send to all subscribers in a topic:

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:

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

Trigger Parameters

Parameter	Required	Description
`workflowId`	Yes	The workflow identifier (not display name)
`to`	Yes	Subscriber ID (string), subscriber object, or topic target
`payload`	No	Data passed to the workflow, validated against `payloadSchema`
`overrides`	No	Provider-specific overrides per channel
`transactionId`	No	Unique ID for idempotency and cancellation
`actor`	No	Subscriber ID or object representing who triggered the action
`context`	No	Key-value pairs for multi-tenancy / organizational context

Overrides

Override provider-specific settings per trigger:

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

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
Subscriber upsert — triggering to a non-existent subscriberId or subscriber object string will create the subscriber with that subscriberId.
Bulk trigger limit is 100 events — chunk larger batches into groups of 100.
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.
Payload is validated against the workflow's payloadSchema — if the workflow defines a schema, the trigger will fail if the payload doesn't match.