useConversationHistory Hook

The useConversationHistory hook gives access to conversations stored in the user's browser, so you can build a history UI where users reopen a past conversation and continue it.

Persistence

Conversation history is on by default: completed conversations are saved to the browser's localStorage as the user chats. To turn it off, pass conversationHistory={{ enabled: false }} to KapaProvider:

<KapaProvider
  integrationId="your-integration-id"
  conversationHistory={{ enabled: false }}
>
  <App />
</KapaProvider>

See KapaProvider for the available options.

Usage

import { useConversationHistory } from "@kapaai/react-sdk";

function HistoryList() {
  const { enabled, threads, restoreThread } = useConversationHistory();

  // Use the hook values and functions to build your UI
  // ...
}

Return values

The useConversationHistory hook returns an object with the following properties:

Property	Type	Description
enabled	boolean	Whether persistence is enabled on the provider.
threads	StoredConversationThread[]	Stored conversations, most recent first. Updates as the user chats.
restoreThread	(threadId: string) => void	Restores a stored conversation so its transcript renders and follow-up questions continue the same thread. Does nothing when persistence is disabled or the thread is not stored.
clear	() => void	Deletes the stored conversations. The open conversation stays on screen but is no longer saved.

StoredConversationThread

Each entry in threads has the following shape:

Property	Type	Description
threadId	string	Backend thread ID of the conversation.
title	string	First question of the conversation, a file name for file-only questions, or an empty string.
createdAt	number	Timestamp (epoch ms) of the first stored answer.
updatedAt	number	Timestamp (epoch ms) of the latest answer. Only a new answer updates it; restoring the conversation or voting does not.
qas	QACompleted[]	The completed question-answer pairs of the conversation, including sources, file attachments, and feedback state.

Examples

History sidebar

import { useConversationHistory } from "@kapaai/react-sdk";

function HistorySidebar() {
  const { enabled, threads, restoreThread } = useConversationHistory();

  if (!enabled || threads.length === 0) {
    return null;
  }

  return (
    <ul>
      {threads.map((thread) => (
        <li key={thread.threadId}>
          <button onClick={() => restoreThread(thread.threadId)}>
            {thread.title || "Untitled conversation"}
          </button>
        </li>
      ))}
    </ul>
  );
}

After restoreThread is called, useChat returns the restored conversation and thread ID, and the next submitQuery continues that thread with full context on the backend.

Clearing history

Call clear from the hook to delete the stored history, for example when a user signs out. The list empties, and the open conversation stays on screen but is no longer saved:

const { clear } = useConversationHistory();

To delete the history outside a KapaProvider, for example after turning the feature off, use clearConversationHistory with the same integrationId and storageKey you give KapaProvider:

import { clearConversationHistory } from "@kapaai/react-sdk";

clearConversationHistory({ integrationId: "your-integration-id" });

Notes

• History is stored unencrypted in localStorage. It is readable by JavaScript running on the page and persists until removed or evicted.
• History is kept per browser and per storage key. Users do not see their conversations on another device or in another browser.
• The provider keeps up to maxThreads conversations (50 by default) and about 1 MB of data, and drops the oldest conversations first when either limit is reached.

Requirements

The useConversationHistory hook must be used within a KapaProvider component.