Skip to main content
A reply sends a message back into the conversation. Agents can reply with plain text, markdown with files, or interactive cards, depending on provider capabilities. Interactive cards include buttons, dropdowns, links, and text inputs. When a user interacts with a card, the onAction handler fires with the action ID and selected value. Use replies when the agent needs to communicate something to the participant in the conversation. Replies are user-facing messages your agent sends back into the conversation. Use signals when you need to update conversation state, trigger workflows, or resolve the thread without messaging the user. The public API is ctx.reply(content, options?). You can also return a string or JSX card from a handler instead of calling ctx.reply() directly.

​
Reply types at a glance

The following table summarizes the reply types your agent can send:
TypeContentAttachmentsUser interaction
Plain textStringVia options.filesNone
MarkdownString with markdownVia options.filesNone
Interactive cardsCard and child componentsNot on cardsButtons, dropdowns, links, inputs trigger onAction
To change a message after you send it, see Edit sent messages.

​
Plain text

Send a simple string reply with ctx.reply(): 
await ctx.reply('Hello! How can I help?');

​
Markdown

Send formatted text by passing a markdown string to ctx.reply(): 
await ctx.reply('**Report generated.** See the attached PDF.');

​
Sending attachments

Include files with string or markdown replies via the optional second argument. When sending attachments, keep these limits in mind:
  • Attachments are limited to 25 MB per file.
  • Files are only supported with string or markdown replies, not card replies.
  • Provide each file with exactly one of url or data.

​
File reference type

Each file uses a FileRef object with the following shape: 
type FileRef = {
  filename: string;
  mimeType?: string;
  data?: string | Uint8Array | ArrayBuffer | Blob;
  url?: string;
};
Use url for larger files. Novu fetches public HTTP(S) URLs server-side. Use data for small generated files in memory. The following examples show both approaches: 
await ctx.reply('Here is your report.', {
  files: [{ filename: 'report.pdf', mimeType: 'application/pdf', url: reportUrl }],
});

​
Interactive cards

Cards are structured messages with buttons, dropdowns, links, and more. Build them with function calls or JSX.
The following example builds a card with the function call API:
import {
  Card, Button, CardText, Actions,
  Select, SelectOption, Divider, CardLink,
} from '@novu/framework';

await ctx.reply(Card({ title: 'Order #1234', children: [
  CardText('Your order is ready for pickup.'),
  Divider(),
  Actions([
    Button({ id: 'ack', label: 'Acknowledge' }),
    Button({ id: 'escalate', label: 'Escalate', style: 'danger' }),
  ]),
  CardLink({ url: 'https://example.com/order/1234', children: 'View details' }),
] }));

​
Available card components

The following table lists the card components you can use in replies:
ComponentDescription
CardContainer with an optional title
CardTextText block inside a card
ButtonInteractive button; id maps to actionId in onAction
ActionsRequired wrapper around Button elements
Select / SelectOptionDropdown; triggers onAction with selected value
DividerVisual separator
CardLinkClickable link
TextInputText input field

Edit sent messages

Update a message in place after sending it with ReplyHandle.

Signals

Metadata, workflow triggers, and conversation resolution.

Connect your first agent

Walk through a full support-bot handler file.