Reply

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. Use ctx.emit when your client needs a named payload during the turn. 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. To send a reply from your backend without going through the bridge handler, use the Send an agent reply API.

Channel support

Capability	Slack	Teams	WhatsApp	Telegram	Email
Plain / rich text	Yes	Yes	Bold / italics	Yes	HTML
Tap-to-respond buttons	Yes	Yes	Yes (up to 3)	Yes	Action links
Outbound file attachments	Yes	Yes	Not yet	Not yet	Not yet
Quote reply	Plain post	Plain post	Native	Native	—

See Channels overview for the full matrix.

Reply types

The following table summarizes the reply types your agent can send:

Type	Content	Attachments	User interaction
Plain text	String	Via `options.files`	None
Markdown	String with markdown	Via `options.files`	None
Interactive cards	`Card` and child components	Not on cards	Buttons, 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.');

Quote reply

Pass quoteReply to pin the reply to a specific inbound message. WhatsApp and Telegram render a native quote. Other channels send a normal post.

await ctx.reply('Your order shipped today.', { quoteReply: message });

Sending attachments

Include files with string or markdown replies via the optional second argument.

Outbound file attachments are delivered on Slack and Microsoft Teams. WhatsApp, Telegram, and email do not support outbound files yet. See Channels overview.

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.
Prefer url for larger files. Inline data is capped at 5 MB per file (and 5 MB aggregate per message).

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

const csv = new TextEncoder().encode('name,total\nNovu,42');
await ctx.reply('CSV generated.', {
  files: [{ filename: 'report.csv', mimeType: 'text/csv', data: csv }],
});

Interactive cards

Cards are structured messages with buttons, dropdowns, links, and more. Build them with function calls or JSX.

Function call API
JSX API

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

Add "jsxImportSource": "@novu/framework" to tsconfig.json, then return JSX from a handler or pass it to ctx.reply():

/** @jsxImportSource @novu/framework */
import {
  Actions, agent, Button, Card, CardLink, CardText, Divider,
} from '@novu/framework';

export const myAgent = agent('my-agent', {
  onMessage: async (message, ctx) => {
    return (
      <Card title="Order #1234">
        <CardText>Your order is ready for pickup.</CardText>
        <Divider />
        <Actions>
          <Button id="ack" label="Acknowledge" />
          <Button id="escalate" label="Escalate" style="danger" />
        </Actions>
        <CardLink url="https://example.com/order/1234">View details</CardLink>
      </Card>
    );
  },
});

You can also pass JSX to ctx.reply():

await ctx.reply(
  <Card title="Order #1234">
    <CardText>Your order is ready for pickup.</CardText>
  </Card>,
);

When a user clicks a button or selects a dropdown value, onAction fires with action.id and action.value. See Handlers and context. On Web Chat, the same tree arrives as a card part. The web UI draws it and calls sendAction.

Available card components

The following table lists the card components you can use in replies:

Component	Description
`Card`	Container with an optional `title`
`CardText`	Text block inside a card
`Button`	Interactive button; `id` maps to `action.id` in `onAction`
`LinkButton`	Button that opens a URL; goes inside `Actions`
`Actions`	Required wrapper around `Button` and `LinkButton` elements
`Select` / `SelectOption`	Dropdown; triggers `onAction` with selected value
`Divider`	Visual separator
`CardLink`	Inline clickable link
`Table`	Structured data table with headers and rows
`Chart`	Bar, line, area, or pie chart
`TextInput`	Text input field

All components are exported from @novu/framework (and from @novu/framework/cards and every server entrypoint), so you do not need to install a separate package. Each one works in both the function call API and the JSX API.

Tables, charts, and link buttons

Table, Chart, and LinkButton render structured content inside a card. On channels with native support (such as Slack), they map to the platform’s rich blocks; on others they fall back to plain text.

/** @jsxImportSource @novu/framework */
import { Actions, Card, Chart, LinkButton, Table } from '@novu/framework';

await ctx.reply(
  <Card title="Weekly deliveries">
    <Table
      caption="Deliveries by channel"
      headers={['Channel', 'Sent']}
      rows={[
        ['Email', '1200'],
        ['SMS', '340'],
      ]}
      pageSize={5}
    />
    <Chart
      title="Sent per day"
      chart={{
        type: 'bar',
        categories: ['Mon', 'Tue'],
        series: [
          { name: 'Email', data: [{ label: 'Mon', value: 400 }, { label: 'Tue', value: 800 }] },
        ],
      }}
    />
    <Actions>
      <LinkButton url="https://dashboard.novu.co/activity">Open dashboard</LinkButton>
    </Actions>
  </Card>,
);

Table takes headers (column labels) and rows (an array of cell-string arrays). Optional caption labels the table, and pageSize sets rows per page on channels that paginate (Slack: 1-100, default 5).
Chart takes a title and a chart definition. Use type: 'bar' | 'line' | 'area' with categories and series, or type: 'pie' with segments. On Slack the title is capped at 50 characters, and series and categories are capped at 12.
LinkButton renders a button that opens a url, unlike CardLink, which renders an inline link. Place it inside Actions.

On Slack, Table ignores per-column align. A chart or table that exceeds the platform limits falls back to a plain-text section.

Edit sent messages

Update a message in place after sending it with ReplyHandle.

Signals

Metadata, workflow triggers, and conversation resolution.

Emit custom events

Send a named payload. Web Chat renders it as a data part.

AI SDK

Build end to end with @novu/framework/ai-sdk.

Send an agent reply API

Send replies from your backend without a bridge handler.

Web Chat cards

Render part.type === 'card' in your product UI and call sendAction.

Getting Started

Channels

Custom Code Agent

Managed Agent

Observability

Channel support

Reply types

Plain text

Markdown

Quote reply

Sending attachments

File reference type

Interactive cards

Available card components

Tables, charts, and link buttons

Edit sent messages

Signals

Emit custom events

AI SDK

Send an agent reply API

Web Chat cards

​Channel support

​Reply types

​Plain text

​Markdown

​Quote reply

​Sending attachments

​File reference type

​Interactive cards

​Available card components

​Tables, charts, and link buttons

​Related

Edit sent messages

Signals

Emit custom events

AI SDK

Send an agent reply API

Web Chat cards

Channel support

Reply types

Plain text

Markdown

Quote reply

Sending attachments

File reference type

Interactive cards

Available card components

Tables, charts, and link buttons

Related