useAgentChat

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

The useAgentChat hook is the headless client for Agent Chat. It loads conversation history, sends messages, streams live turns over the socket, and exposes pending tool approvals. Use it inside NovuProvider. Product guide: Build the UI.

Hook parameters

Property	Type	Description
`agentId`	`string`	Required. Public agent identifier from the dashboard.
`conversationId`	`string`	Resume this conversation and load history on mount. Omit to start a new chat. The first `sendMessage` creates the conversation.
`agentHash`	`string`	HMAC-SHA256 of `agentId` with the environment secret. Required when Security HMAC is on for the Agent Chat integration.
`onSuccess`	`(data: LoadConversationResult) => void`	Fires after a history fetch succeeds.
`onError`	`(error: NovuError \| AgentChatPlanLimitError) => void`	Fires when a load, send, or action response fails.
`onMessage`	`(message: AgentMessage) => void`	Fires once per new message id. History pages are silent. The first envelope of a turn can create an empty assistant message before text arrives. A send that never reaches the server does not fire. The message status becomes `failed` instead.
`onActionRequested`	`(action: AgentPendingAction) => void`	Fires once per pending action, including actions still pending on mount. Paging backwards is silent.
`onEvent`	`(envelope: AgentEventEnvelope) => void`	Raw live envelopes for this conversation. Duplicate envelopes that the store drops do not fire.

Return value

Property	Type	Description
`messages`	`AgentMessage[]`	Folded timeline for the current conversation.
`pendingActions`	`AgentPendingAction[]`	Tool approvals and MCP connect items that are still pending. Derived from `messages`.
`conversationId`	`string \| undefined`	Server conversation id after create or resume. Undefined until the first successful send on a new chat.
`error`	`NovuError \| AgentChatPlanLimitError`	Last error from load, send, or `respondToAction`.
`isLoading`	`boolean`	True until the first history fetch completes. False when there is no `conversationId` prop.
`isFetching`	`boolean`	True while a history request is in flight.
`isRunning`	`boolean`	True while the agent turn is in progress.
`typing`	`AgentConversationTyping \| undefined`	Ephemeral typing indicator. Absent when the agent is not typing.
`status`	`AgentConversationStatus`	`active` or `resolved`.
`hasMore`	`boolean`	True when older history pages are available via `fetchMore`.
`refetch`	`() => Promise<void>`	Reload the newest history page. No-op when there is no conversation id.
`fetchMore`	`() => Promise<{ data?: { messages: AgentMessage[]; hasMore: boolean }; error?: NovuError }>`	Load an older history page.
`sendMessage`	`(text: string) => Promise<{ data?: SendMessageResult; error?: NovuError \| AgentChatPlanLimitError }>`	Send a user message. Creates a conversation when `conversationId` is omitted.
`respondToAction`	`(args: { actionId: string; decision: 'approved' \| 'denied' }) => Promise<{ data?: RespondToActionResult; error?: NovuError \| AgentChatPlanLimitError }>`	Approve or deny a pending `tool-approval`. Pass `action.id` from `pendingActions`.

Message type

Property	Type	Description
`id`	`string`	Message id. Optimistic local ids are replaced after the server ack.
`role`	`AgentMessageRole`	Sender role (`user` or `assistant`).
`parts`	`AgentMessagePart[]`	Ordered content. See part types below.
`createdAt`	`string`	ISO timestamp.
`status`	`'sending' \| 'sent' \| 'failed'`	Delivery status for the local send.

Part types

`type`	When you see it
`text`	Visible message text. `state` is `streaming` or `done`.
`thinking`	Chain-of-thought / plan text while the agent reasons.
`tool`	Tool call and result.
`approval`	Gated tool waiting on the subscriber. Use `pendingActions` + `respondToAction`.
`mcp-connection`	MCP server connect card. Open `authorizeUrl` in the browser.
`card`	Structured card payload (`card` object).
`file`	File attachment metadata.
`source`	Citation (`url` or `document`).

Pending actions

pendingActions is derived from pending approval and mcp-connection parts.

`type`	What to do
`tool-approval`	Call `respondToAction({ actionId: action.id, decision: 'approved' \| 'denied' })`.
`mcp-connection`	Open `authorizeUrl` in the browser. Do not invent action ids.

Plan limit error

AgentChatPlanLimitError is thrown (and returned on the hook error field) when the organization is over a plan limit. The HTTP status is 402.

Property	Type	Description
`name`	`'AgentChatPlanLimitError'`	Discriminator.
`reason`	`'agents' \| 'channels' \| 'conversations'`	Which limit blocked the request.
`message`	`string`	Human-readable error.

JavaScript SDK

The same client lives on novu.agentChat in @novu/js: sendMessage, loadConversation, fetchMore, respondToAction, subscribe, unsubscribe.

Getting Started

Integrate <Inbox />

Integrate <Subscription />

Build a Workflow

Integrate Channels Providers

SDKs

Developer

Account

Build with AI

Additional Resources

useAgentChat

Hook parameters

Return value

Message type

Part types

Pending actions

Plan limit error

JavaScript SDK

​Hook parameters

​Return value

​Message type

​Part types

​Pending actions

​Plan limit error

​JavaScript SDK

Hook parameters

Return value

Message type

Part types

Pending actions

Plan limit error

JavaScript SDK