Web Chat

Web Chat is how you embed an agent inside your own app. It is an Agent Communication Infrastructure (ACI) channel, the same layer Slack and Teams use, except you own the surface: message list, composer, and layout. The React client is useWebChat from @novu/react. There is no prebuilt <WebChat /> component. If you are not on React, use conversation() from @novu/js.

Setup

Create an agent and keep it active. Then add the channel in the dashboard:

Open the agent in the Novu dashboard.
Add Web Chat. Novu creates the novu-web-chat integration if it is missing.

Install

Collect these values from the dashboard, then install @novu/react:

Application identifier from API Keys
A subscriber id for the signed-in person
The public agent identifier from the agent page

npm install @novu/react

@novu/react requires React 18 or later (^18.0.0 or ^19.0.0).

Place NovuProvider above the chat. useWebChat gets the Novu client from that context.

import { NovuProvider } from '@novu/react';

export function App() {
  return (
    <NovuProvider
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
    >
      <Chat />
    </NovuProvider>
  );
}

import { NovuProvider } from '@novu/react';

export function App() {
  return (
    <NovuProvider
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      apiUrl="https://eu.api.novu.co"
      socketUrl="wss://eu.socket.novu.co"
    >
      <Chat />
    </NovuProvider>
  );
}

NovuProvider signs the subscriber in. useWebChat selects which agent to talk to.

Replace YOUR_* placeholders with values from API Keys and Subscribers.

Add Novu Web Chat to my React app

Open in Cursor

Send a first message

Call useWebChat inside NovuProvider. Render text parts, then send with sendMessage.

const { messages, sendMessage, isRunning, isLoading, error } =
  useWebChat({
    agentId: 'YOUR_AGENT_IDENTIFIER',
  });

{error ? <p>{error.message}</p> : null}

<ul>
  {messages.map((message) => (
    <li key={message.id}>
      <strong>{message.role}</strong>{' '}
      {message.parts.map((part, index) =>
        part.type === 'text' ? (
          <span key={index}>{part.text}</span>
        ) : null
      )}
    </li>
  ))}
</ul>

<form
  onSubmit={(event) => {
    event.preventDefault();
    const form = event.currentTarget;
    const input = form.elements.namedItem('text') as HTMLInputElement;
    void sendMessage(input.value);
    form.reset();
  }}
>
  <input name="text" disabled={isRunning || isLoading} />
  <button type="submit" disabled={isRunning || isLoading}>
    Send
  </button>
</form>

Omit conversationId to start a new chat. The first successful send creates the conversation.

Messages

Render message parts in the timeline.

Tools

Tool calls, approval, and MCP connect.

Generative UI

Custom data parts and structured UI.

Conversations

Resume chats, load history, and reconnect.

assistant-ui

Build with the assistant-ui library.

Security

HMAC hashes before you ship to production.

useWebChat

Hook props, return value, and callbacks.

JavaScript SDK

Call loadWebChat(novu), then novu.webChat.conversation() in @novu/js.

Getting Started

Channels

Custom Code Agent

Managed Agent

Observability

Setup

Install

Send a first message

What to read next

Messages

Tools

Generative UI

Conversations

assistant-ui

Security

useWebChat

JavaScript SDK

​Setup

​Install

​Send a first message

​What to read next

Messages

Tools

Generative UI

Conversations

assistant-ui

Security

useWebChat

JavaScript SDK

Setup

Install

Send a first message

What to read next