Add your existing agent to your React app with Novu Web Chat

You may already have an agent that your users talk to on Slack, Teams, or another channel. We’ve added a new channel: Web Chat. Most times your users have questions and tasks they want your agent to do while using your product. Giving them a way to reach the same agent there lets them stay in the flow of what they're doing.

Novu Web Chat brings that conversation into your app. You build the React interface, including the message list and composer. Novu handles message delivery and conversation state between that interface and your existing agent. The agent keeps its own runtime, instructions, and tools.

In this guide, we'll connect an existing agent to a small React chat interface and send the first message. Then we'll use a release dashboard demo to show what the experience looks like when the agent takes an action through a tool. You can follow the integration steps with your own agent, regardless of the task it performs.

What Web Chat adds to your existing agent

Web Chat is a headless channel. There is no prebuilt <WebChat /> component. The useWebChat hook from @novu/react gives your interface access to messages, sending, and conversation state. Your components decide how those messages appear and where chat belongs in the product.

You don't need to move your agent's logic into Novu. Connect the Web Chat channel to an agent that is already running, then place the client interface wherever your users need it: a dashboard, a support page, or a workflow in your app. What the agent can actually do still depends on its instructions, tools, and access to the right data.

Before you start

You'll need a React 18 or 19 app, a Novu account, and an active agent connected to Novu. If your agent runs in your own code, its bridge must be reachable when you test the chat. If you haven't connected the agent yet, follow the custom code agent connection guide first.

Collect these values:

• The application identifier from API Keys in the Novu dashboard.
• The subscriber ID that identifies the signed-in user in your app.
• The agent's public identifier from its page in the dashboard.

The application and agent identifiers can be used in client code. Keep your Novu secret key on the server. We'll return to subscriber and agent verification before shipping.

Add Web Chat to the agent

Open the agent in the Novu dashboard and add Web Chat as a channel. Novu creates the novu-web-chat integration if your environment doesn't already have one. Keep the agent active.

Build the chat in React

Install the React package:

npm install @novu/react

Place NovuProvider above the chat and use useWebChat inside it. This starting point renders text messages and a composer. Replace the identifiers with values from your environment and your authenticated app user.

import { useState, type FormEvent } from 'react';
import { NovuProvider, useWebChat } from '@novu/react';

const agentId = 'YOUR_AGENT_IDENTIFIER';

function Chat() {
  const [draft, setDraft] = useState('');
  const {
    messages,
    sendMessage,
    retryMessage,
    isLoading,
    isRunning,
    error,
  } = useWebChat({ agentId });

  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    const text = draft.trim();
    if (!text || isLoading || isRunning) return;

    const { error: sendError } = await sendMessage(text);
    if (!sendError) setDraft('');
  }

  return (
    <section aria-label="Agent chat">
      <ul aria-label="Conversation">
        {messages.map((message) => (
          <li key={message.id}>
            <strong>{message.role === 'user' ? 'You' : 'Agent'}: </strong>
            {message.parts.map((part, index) =>
              part.type === 'text' ? (
                <span key={index}>{part.text}</span>
              ) : null
            )}
            {message.status === 'failed' && (
              <button
                type="button"
                onClick={() => void retryMessage(message.id)}
              >
                Retry
              </button>
            )}
          </li>
        ))}
      </ul>

      {error && <p role="alert">{error.message}</p>}
      {isRunning && <p>Agent is responding...</p>}

      <form onSubmit={handleSubmit}>
        <label htmlFor="chat-message">Message</label>
        <input
          id="chat-message"
          value={draft}
          onChange={(event) => setDraft(event.target.value)}
          disabled={isLoading || isRunning}
        />
        <button
          type="submit"
          disabled={!draft.trim() || isLoading || isRunning}
        >
          Send
        </button>
      </form>
    </section>
  );
}

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

NovuProvider identifies the subscriber. agentId selects the agent connected to Web Chat. The hook returns a timeline of messages, and each message contains ordered parts. This first version shows only text parts. It won't display a tool's progress, an approval request, or a connection prompt that your agent might send. We'll account for those when we look at the demo.

Send the first message

Start the React app, make sure the agent is active and reachable, and open the page as the user represented by the subscriber ID. Send a message your agent can handle. You should see your message and its reply in the same interface.

If nothing appears, check the three identifiers, the Web Chat channel assignment, and the agent connection. For a custom code agent, check that Novu can reach its bridge. The Web Chat setup guide also covers region-specific configuration.

At this point, you've connected the product UI to the agent. What happens next depends on the product and the tools your agent can use. To make that concrete, here's the app we built for this guide.

Example: Create a Linear issue from a release dashboard

We created a product dashboard where users can check the status of a release and see issues affecting it. We built a small React version of that dashboard and added a Web Chat drawer, opened from an “Ask the release agent” button next to the release information.

A user who spots a checkout problem can describe it in the chat and ask the existing agent to create a Linear issue. The agent has access to a Linear tool, so it can perform the action and return a link to the new issue while the user stays on the dashboard.

The React integration does not need a Linear-specific Web Chat API. The tool belongs to the agent. The chat interface does need to render what the agent sends. A tool call appears as a tool message part. If your agent pauses for tool approval or a Model Context Protocol (MCP) connection, the user needs a way to complete that step in the chat. Those are separate flows, exposed through pendingActions and respondToAction rather than the message list:

const { messages, pendingActions, respondToAction /* …as before */ } = useWebChat({ agentId });

// Inside the message parts map, alongside the 'text' case:
if (part.type === 'tool') {
  return (
    <p key={index}>
      Tool: {part.toolName} ({part.state})
    </p>
  );
}

// Alongside the message list, rendered once per pending item:
{pendingActions.map((action) =>
  action.type === 'approval' ? (
    <div key={action.approvalId}>
      <p>Approve “{action.toolName}”?</p>
      <button
        onClick={() =>
          void respondToAction({ approvalId: action.approvalId, decision: 'approved' })
        }
      >
        Approve
      </button>
      <button
        onClick={() =>
          void respondToAction({ approvalId: action.approvalId, decision: 'denied' })
        }
      >
        Deny
      </button>
    </div>
  ) : null
)}

That's enough to show a tool running and let a user approve or deny it. The full demo also renders an mcp-connection authorization prompt and a more detailed tool-output view — rather than reproducing all of that here, see the full source linked below.

40k starsNovu on GitHub

Link to the public GitHub repo with the complete LaunchBoard demo

For this demo, the issue details are in the user's request. If you want the agent to act on a selected item in your app instead, you must pass that item's context to the agent. Simply displaying the item beside the chat does not give the agent access to it.

The same integration can support another task with a different agent and tool. A support agent could look up an account record. An operations agent could update an incident. The React surface and the Web Chat connection remain the starting point; the agent's permissions and UI states depend on the action you choose.

Let users return to the conversation

The starting example creates a conversation when the first message is sent. To reopen it later, capture the conversationId returned by useWebChat, store it for the signed-in user, and pass it back to the hook. Novu then loads that conversation's history. If your product needs a list of past conversations, use the separate conversation-list API described in the conversations guide.

Before shipping, enable the relevant HMAC checks and generate the hashes on your server. subscriberHash verifies the subscriber, while agentHash restricts which agent the client can address. The Web Chat security guide shows where each hash belongs.

You now have the first conversation in your React app and a path to adapt it to the work your agent already does. Start with the message parts and pending actions your agent sends, then style the interface and decide how your users return to earlier chats.