Build the Agent Chat UI

Agent Chat is in closed beta. Contact us at [email protected] to get access.

Build a two-way agent chat in your React app. You supply the UI. Novu supplies conversation state, delivery, and the live socket.

Prerequisites

Complete channel setup first. Then you need:

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

Install and wrap NovuProvider

npm install @novu/react

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

useAgentChat reads the Novu client from context. Place NovuProvider above the chat.

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 authenticates the subscriber. useAgentChat selects which agent to talk to.

Add Novu Agent Chat to my React app

Open in Cursor

Send a message

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

const { sendMessage, isRunning, isLoading } = useAgentChat({
  agentId: 'YOUR_AGENT_IDENTIFIER',
});

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

const { sendMessage, isRunning, isLoading } = useAgentChat({
  agentId: 'YOUR_AGENT_IDENTIFIER',
});

<PromptInput
  onSubmit={async (message) => {
    if (!message.text.trim() || isRunning || isLoading) {
      return;
    }

    const { data } = await sendMessage(message.text);
    // data.conversationId — store this to resume later
  }}
>
  <PromptInputBody>
    <PromptInputTextarea disabled={isRunning || isLoading} placeholder="Message" />
  </PromptInputBody>
  <PromptInputFooter>
    <PromptInputSubmit
      className="ml-auto"
      disabled={isRunning || isLoading}
      status={isRunning ? 'streaming' : 'ready'}
    />
  </PromptInputFooter>
</PromptInput>

If isRunning or isLoading is true, disable the composer. The agent is still working on the turn.

Receive and render parts

messages is the ordered timeline. Each message has role (user or assistant) and parts. Start with type === 'text'. Then handle the other part types as you need them.

`type`	What to render
`text`	Visible body. `state` is `streaming` or `done`.
`thinking`	Plan text while the agent reasons.
`tool`	Tool call and result.
`approval`	Gated tool. Use `pendingActions` and `respondToAction`.
`mcp-connection`	MCP connect card. Open `authorizeUrl`.
`card`	Structured card payload.
`file`	File attachment metadata.
`source`	Citation (`url` or `document`).

const { messages } = useAgentChat({ agentId: 'YOUR_AGENT_IDENTIFIER' });

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

const { messages } = useAgentChat({ agentId: 'YOUR_AGENT_IDENTIFIER' });

<Conversation>
  <ConversationContent>
    {messages.map((message) => (
      <Message key={message.id} from={message.role}>
        <MessageContent>
          {message.parts.map((part, index) =>
            part.type === 'text' ? <MessageResponse key={index}>{part.text}</MessageResponse> : null
          )}
        </MessageContent>
      </Message>
    ))}
  </ConversationContent>
  <ConversationScrollButton />
</Conversation>

Full field tables: useAgentChat.

Thinking and running

While the agent turn is in progress, isRunning is true. typing is present when the agent is typing. Assistant messages can include thinking parts before text arrives.

const { messages, isRunning, typing } = useAgentChat({
  agentId: 'YOUR_AGENT_IDENTIFIER',
});

{isRunning ? <p>{typing?.status ?? 'Working…'}</p> : null}

{messages.map((message) =>
  message.parts.map((part, index) => {
    if (part.type === 'thinking') {
      return <em key={index}>{part.text}</em>;
    }

    if (part.type === 'text') {
      return <span key={index}>{part.text}</span>;
    }

    return null;
  })
)}

const { messages, isRunning, typing } = useAgentChat({
  agentId: 'YOUR_AGENT_IDENTIFIER',
});

{isRunning ? <Shimmer>{typing?.status ?? 'Working…'}</Shimmer> : null}

{messages.map((message) => (
  <Message key={message.id} from={message.role}>
    <MessageContent>
      {message.parts.map((part, index) => {
        if (part.type === 'thinking') {
          return (
            <ChainOfThought key={index} defaultOpen={part.state === 'streaming'}>
              <ChainOfThoughtContent>
                <ChainOfThoughtStep
                  label={part.text}
                  status={part.state === 'streaming' ? 'active' : 'complete'}
                />
              </ChainOfThoughtContent>
            </ChainOfThought>
          );
        }

        if (part.type === 'text') {
          return <MessageResponse key={index}>{part.text}</MessageResponse>;
        }

        return null;
      })}
    </MessageContent>
  </Message>
))}

The first envelope of a turn can create an empty assistant message before any text is folded in. Keep that row in the list. Then fill it as parts arrive.

Tool approval and MCP connect

pendingActions lists waits that block the turn. Do not mix the two action types.

`action.type`	What to do
`tool-approval`	Call `respondToAction` with `action.id` and `approved` or `denied`.
`mcp-connection`	Open `action.authorizeUrl` in the browser. Do not call `respondToAction`.

const { pendingActions, respondToAction } = useAgentChat({
  agentId: 'YOUR_AGENT_IDENTIFIER',
});

{pendingActions.map((action) => {
  if (action.type === 'tool-approval') {
    return (
      <button
        key={action.id}
        type="button"
        onClick={() => void respondToAction({ actionId: action.id, decision: 'approved' })}
      >
        Approve {action.toolName}
      </button>
    );
  }

  if (action.type === 'mcp-connection') {
    return (
      <a key={action.id} href={action.authorizeUrl} target="_blank" rel="noreferrer">
        Connect {action.displayName}
      </a>
    );
  }

  return null;
})}

const { pendingActions, respondToAction } = useAgentChat({
  agentId: 'YOUR_AGENT_IDENTIFIER',
});

{pendingActions.map((action) => {
  if (action.type === 'tool-approval') {
    return (
      <Message key={action.id} from="assistant">
        <MessageContent>
          <button
            type="button"
            onClick={() => void respondToAction({ actionId: action.id, decision: 'approved' })}
          >
            Approve {action.toolName}
          </button>
        </MessageContent>
      </Message>
    );
  }

  if (action.type === 'mcp-connection') {
    return (
      <Message key={action.id} from="assistant">
        <MessageContent>
          <a href={action.authorizeUrl} target="_blank" rel="noreferrer">
            Connect {action.displayName}
          </a>
        </MessageContent>
      </Message>
    );
  }

  return null;
})}

Pass action.id from pendingActions. Do not invent approve or deny ids.

Resume or start another chat

Pass conversationId so the hook loads history on mount.

useAgentChat({
  agentId: 'YOUR_AGENT_IDENTIFIER',
  conversationId, // omit to start a new chat
});

const { data } = await sendMessage(text);
// persist data.conversationId and pass it back as conversationId

Store the conversationId that sendMessage returns, or the conversationId field on the hook result. On the next visit, pass that id back in. The hook has no list-conversations API. You store the ids that you want to reopen. To start another chat, remount the component without conversationId, or clear the prop.

Switch agent

agentId selects the agent. If the identifier changes, remount with the new agentId. Omit conversationId unless that conversation belongs to the new agent. A conversation id from a different agent does not resume.

Going to production

HMAC is off by default. Turn it on before you ship. Agent Chat can require two hashes. Each hash has its own dashboard toggle.

Hash	Toggle	Input	Where you pass it
`subscriberHash`	Novu In-App integration	`subscriberId`	`NovuProvider`
`agentHash`	Agent Chat integration	agent identifier	`useAgentChat`

Both hashes use the same secret: the environment API secret from API Keys. Compute them on your server. Do not compute them in the browser.

subscriberHash

subscriberHash authenticates the signed-in subscriber. Without it, another person can guess a subscriberId and open that subscriber’s session, including Agent Chat. If Security HMAC encryption is on for Novu In-App, pass subscriberHash to NovuProvider. The hash is HMAC-SHA256(secretKey, subscriberId) as a lowercase hex string. Generation recipes (Node.js, Python, and more): Secure your Inbox with HMAC.

agentHash

agentHash authenticates which agent the subscriber can talk to. Without it, a client can send any public agent identifier that is linked to Agent Chat. If Security HMAC encryption is on for Agent Chat:

Open Integrations.
Select the Agent Chat integration.
Enable Security HMAC encryption.
On your server, compute HMAC-SHA256(secretKey, agentIdentifier) as a lowercase hex string.
Pass that value as agentHash to useAgentChat.

<NovuProvider
  applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
  subscriber="YOUR_SUBSCRIBER_ID"
  subscriberHash="YOUR_SUBSCRIBER_HASH"
>
  <Chat />
</NovuProvider>

useAgentChat({
  agentId: 'YOUR_AGENT_IDENTIFIER',
  agentHash: 'YOUR_AGENT_HASH',
});

If only one toggle is on, pass only that hash. If both toggles are on, pass both hashes.

Getting Started

Channels

Custom Code Agent

Managed Agent

Observability

Build the Agent Chat UI

Prerequisites

Install and wrap NovuProvider

Send a message

Receive and render parts

Thinking and running

Tool approval and MCP connect

Resume or start another chat

Switch agent

Going to production

subscriberHash

agentHash

Next steps

useAgentChat reference

Channel setup

​Prerequisites

​Install and wrap NovuProvider

​Send a message

​Receive and render parts

​Thinking and running

​Tool approval and MCP connect

​Resume or start another chat

​Switch agent

​Going to production

​subscriberHash

​agentHash

​Next steps

useAgentChat reference

Channel setup

Prerequisites

Install and wrap NovuProvider

Send a message

Receive and render parts

Thinking and running

Tool approval and MCP connect

Resume or start another chat

Switch agent

Going to production

subscriberHash

agentHash

Next steps