Skip to main content
Novu gives your handler the same building blocks whether the message came from Slack, email, or another provider, and whether you call an LLM or plain TypeScript.

​
Event handlers

Event handlers are functions that respond to events in a conversation. Your agent can respond to four event types:
HandlerWhen it runsCommon use case
onMessageA user sends a message in the conversationProcess the message and reply
onActionA user clicks a button or selects a value in an interactive cardHandle form submissions, button clicks, dropdown selections
onReactionA user adds or removes a reactionCapture feedback or trigger a follow-up
onResolveThe conversation is marked as resolvedClean up state, log analytics, or send a summary
Handlers are where the communication layer connects to your application logic. For example, an onMessage handler receives the user’s message, passes conversation context to an LLM or custom function, and sends the response back through Novu.

​
Context object

Each event handler receives a context object with the information needed to understand the current event and respond. Depending on the event type, it can include:
  • The incoming message
  • The current conversation state and metadata
  • The resolved subscriber (when available)
  • Recent conversation history
  • Provider information
  • Platform-specific details, such as thread or channel identifiers
  • Methods for replying, updating metadata, triggering workflows, or resolving the conversation
The context object is how your code talks to Novu. You do not call Slack, Teams, or email APIs directly in the handler.

​
Event handling flow

When a user messages your agent:
1

User sends a message

A user sends a message from a connected provider (for example, Slack).
2

Novu receives the event

Novu receives the event through the provider connection.
3

Novu maps the thread

Novu maps the provider thread to a conversation and resolves the platform user to a subscriber, when possible.
4

Novu calls onMessage

Novu calls the agent’s onMessage handler with the context object.
5

Handler passes context to agent logic

Your handler passes the message and conversation context to your agent logic.
6

Agent logic decides next action

Your agent logic decides what should happen next.
7

Handler sends reply or signals

Your handler sends a reply, emits signals, or both.
8

Novu delivers the reply

Novu delivers the reply back to the provider thread.
9

Novu records conversation state

Novu records messages, participants, metadata, signals, and conversation status.
The same agent logic works across all connected providers because Novu handles the provider-specific communication layer. Connecting a new provider does not require changing your agent code.

​
onMessage

onMessage fires every time a user sends a message in a conversation with your agent. 
/** @jsxImportSource @novu/framework */
import { agent } from '@novu/framework';

export const myAgent = agent('my-agent', {
  onMessage: async ({ message, ctx }) => {
    const userMessage = message.text ?? '';
    const conversationHistory = ctx.history;
    const subscriber = ctx.subscriber;

    const response = await yourLLM.chat(userMessage, conversationHistory);

    ctx.metadata.set('lastIntent', response.intent);
    await ctx.reply(response.text);
  },
});

​
Handling attachments

Inbound messages can include file attachments when the platform supports them. Novu normalizes files into message.attachments with short-lived signed URLs. Keep in mind:
  • Download attachment URLs promptly inside your handler.
  • Signed links are valid for 15 minutes.
  • Inbound attachments are limited to 25 MB per file.
import { agent } from '@novu/framework';

export const myAgent = agent('my-agent', {
  onMessage: async ({ message, ctx }) => {
    const attachments = message.attachments ?? [];

    for (const file of attachments) {
      // file.type: 'image', 'document', 'audio', 'video'
      // file.url: short-lived download URL
      // file.name: original filename
      // file.mimeType: e.g. 'image/jpeg'
      // file.size: size in bytes
    }
  },
});

​
onAction

onAction fires when a user clicks a button or selects a value in an interactive card. See Interactive cards. 
import { agent } from '@novu/framework';

export const myAgent = agent('my-agent', {
  onAction: async ({ actionId, value, ctx }) => {
    if (actionId === 'approve' && value === 'true') {
      await ctx.reply('Request approved!');
      ctx.trigger('approval-workflow', {
        to: ctx.subscriber?.subscriberId,
        payload: { approved: true },
      });
    }
  },
});

​
onReaction

onReaction fires when a user adds or removes an emoji reaction on a message. 
import { agent } from '@novu/framework';

export const myAgent = agent('my-agent', {
  onReaction: async ({ emoji, added, message, ctx }) => {
    if (emoji.name === 'thumbs_up' && added) {
      ctx.metadata.set('userSatisfied', true);
    } else if (emoji.name === 'thumbs_down' && added) {
      ctx.metadata.set('userUnsatisfied', true);
    }
    await ctx.reply('Thank you for your feedback!');
  },
});

​
onResolve

onResolve fires when the conversation is marked as resolved via ctx.resolve() or the resolve signal. 
import { agent } from '@novu/framework';

export const myAgent = agent('my-agent', {
  onResolve: async (ctx) => {
    ctx.metadata.set('resolvedAt', new Date().toISOString());
  },
});

Reply

Send plain text, markdown, attachments, and interactive cards.

Edit sent messages

Update a message in place after sending it with ReplyHandle.

Connect your first agent

Walk through a full support-bot handler file.