Novu

Create a new bot

Scaffold a Next.js bot with the Novu adapter using create-chat-sdk:

The generated app uses the Memory state adapter for local development. To add the adapter to an existing app, start at Install.

Install

Quick start

Wire the adapter into your Chat SDK app:

import { Chat } from "chat";
import { createMemoryState } from "@chat-adapter/state-memory";
import { createNovuAdapter } from "@novu/chat-sdk-adapter";

const novu = createNovuAdapter();

const chat = new Chat({
  userName: "support",
  adapters: { novu },
  state: createMemoryState(),
});

chat.onNewMention(async (thread, message) => {
  await thread.post(`Hi! You said: ${message.text}`);
});

chat.onSubscribedMessage(async (thread, message) => {
  await thread.post(`echo: ${message.text}`);
});

await chat.initialize();

Then connect your agent to a real channel. Run the command below and pick Slack, Email, Telegram, WhatsApp, or Microsoft Teams:

npx novu connect --runtime chat-sdk

The CLI authenticates your Novu account, creates your bridge agent, and writes NOVU_SECRET_KEY and NOVU_AGENT_IDENTIFIER to your env. It also provisions the provider integration, helps you set up the bot entity, and stores multi-tenant user OAuth credentials. See Platform setup for the full flow.

Platform setup

Novu handles OAuth, token storage and rotation, and Slack Connect for each channel, so no platform secrets live in your app. npx novu connect --runtime chat-sdk runs an interactive flow:

1. Authenticate: sign in to Novu, or pass --secret-key for an existing account.
2. Create or reuse a bridge agent. Use one agent per Chat SDK app.
3. Pick a channel: Slack, Email, Telegram, WhatsApp, Microsoft Teams, or skip for now.
4. Finish the handoff: the CLI creates the provider integration and guides you through the last step, such as Slack OAuth, a BotFather token, or sending a test email.

What the CLI sets up for each channel:

Re-run npx novu connect --runtime chat-sdk to add another channel or refresh credentials. Each run creates a new agent unless you pick an existing one.

Configuration

Set these through the environment (the CLI writes them for you) or pass them to createNovuAdapter({ ... }):

Environment variables

Channels

One handler set serves Slack, Microsoft Teams, WhatsApp, Telegram, and email, with no per-channel code.

Novu context

Every channel resolves to a single Novu subscriber mapped to your own user, and Novu records delivery status and the full conversation history for every message. Inside any handler, getNovuContext(thread) gives you access to this Novu data:

import { getNovuContext } from "@novu/chat-sdk-adapter";

chat.onSubscribedMessage(async (thread, message) => {
  const ctx = getNovuContext(thread);

  const subscriber = await ctx.getSubscriber(); // email, phone, locale, custom data
  const history = await ctx.getHistory(); // canonical transcript, ideal for LLM context
  const ticketId = await ctx.getMetadata("ticketId");

  if (subscriber?.data?.plan === "enterprise") {
    await thread.post("Priority support enabled.");
  }
});

Proactive multi-channel notifications

Your agent can push notifications outside an active conversation by triggering a Novu workflow. Define the workflow once in Novu with the channels you want (Slack, email, WhatsApp, and so on), and a single trigger call delivers to every step in that workflow.

By default, the trigger targets the subscriber on the current conversation. Pass explicit recipients to notify someone else or a topic:

import { getNovuContext } from "@novu/chat-sdk-adapter";

chat.onSubscribedMessage(async (thread, message) => {
  const ctx = getNovuContext(thread);

  // Notify the same user on every channel in the "order-shipped" workflow.
  await ctx.trigger("order-shipped", {
    payload: {
      orderId: "1234",
      trackingUrl: "https://example.com/track/1234",
    },
  });

  // Escalate to a different subscriber on a separate workflow.
  await ctx.trigger("manager-alert", {
    to: { subscriberId: "manager-42" },
    payload: { reason: message.text },
  });

  // Fan out to a Novu topic.
  await ctx.trigger("incident-broadcast", {
    to: { type: "Topic", topicKey: "on-call" },
    payload: { severity: "high" },
  });
});

When the user replies on any channel Novu delivered to, the message routes back through the same bridge to your existing handlers, so one agent loop handles both proactive notifications and conversational replies.

Create workflows in the Novu dashboard or through the API, then reference them by workflow ID from your agent.

Email

Pick Email in the connect channel picker, or re-run npx novu connect --runtime chat-sdk and choose it from the menu.

Novu provisions a unique inbound address for your agent, for example my-agent-abc@agentconnect.sh. Anyone can email that address. Novu normalizes the thread and forwards it to your Chat SDK bridge, your agent replies from the same inbox, and the conversation continues over email like any other channel.

Unlike Slack or Telegram, an email conversation starts with the user sending the first message. The CLI opens a pre-filled draft so you can send a test email and confirm the connection.

The shared @agentconnect.sh address works without further setup. For production, configure your own inbound domain in the Novu dashboard (Domains → add domain → verify DNS) to route mail to your agent on @yourcompany.com while keeping the same bridge handlers.

Use getNovuContext(thread).getEmailContext() inside handlers for email-specific metadata such as the routing domain and thread headers.

Feature support

Resources

• Adapter reference: @novu/chat-sdk-adapter
• Novu docs
• Novu official website

Example app

novu-chat-sdk-example is a complete Next.js boilerplate with a live bridge route, setup UI, bridge-status panel, and a handler set covering every capability. It ships one bot that exercises each handler. Message it on any connected channel:

Handler coverage: onNewMention, onSubscribedMessage, onAction (button clicks), and onReaction.