Chat History Storage

You can esily create chat endpoints that support chat history.

Core Concepts

Chat History: Chat history is a record of the conversation between the user and the chat agent. It can be used to provide context to the chat agent and to maintain the state of the conversation.
Chat ID: Each conversation is recognized by a unique chat ID. The chat ID is used to store and retrieve the chat history.
Continue Conversation: All that the user needs to do to continue a past or ongoing conversation, is to provide the chat ID of the conversation.

First time that a conversation query is sent to a chat endpoint (that has chat history enabled), no chatId needs to be provided. A unique chatId will be generated and returned in the response. This chatId can be used to continue the conversation in the future.

Chat History Store

You can provide an instance of any chat history store to the defineChatEndpoint function. If using a custom chat history store, all you have to ensure is that the chat history store instance you provide implements the ChatHistoryStore interface.

import { ChatHistoryStore } from 'qvikchat/history';
 
export class CustomChatHistoryStore implements ChatHistoryStore {
    ...
}

Below code gives an idea of how the ChatHistoryStore interface is defined. Actual implementation may vary depending on the version of QvikChat you're using.

/**
 * Represents a store for managing chat history.
 */
export interface ChatHistoryStore {
  /**
   * The collection of chat history records.
   */
  history: ChatHistoryCollection | CollectionReference;
  /**
   * Add new chat history to the store. Returns chat ID of the new chat history.
   * @param messages add new chat history to the store
   * @returns chat ID of the new chat history
   */
  addChatHistory: (messages?: MessageData[]) => Promise<string>;
  /**
   * Update existing chat history in the store. Overwrites existing messages with new messages.
   * @param chatId ID of the chat history to update
   * @param messages messages to add to the chat history
   * @throws Error if unable to update chat history
   */
  updateChatHistory: (
    chatId: string,
    messages: MessageData[]
  ) => Promise<boolean> | Promise<void>;
  /**
   * Add messages to an existing chat history in the store.
   * @param chatId ID of the chat history to update
   * @param messages messages to add to the chat history
   * @throws Error if unable to add messages to chat history
   */
  addMessages: (
    chatId: string,
    messages: MessageData[]
  ) => Promise<boolean> | Promise<void>;
  /**
   * Get chat history from the store for the specified chat ID.
   * @param chatId Chat ID for the chat history to retrieve
   * @returns Array of messages pretaining to the chat history
   * @throws Error if unable to retrieve chat history
   */
  getChatHistory: (chatId: string) => Promise<MessageData[]>;
  /**
   * Delete chat history from the store for the specified chat ID.
   * @param chatId Chat ID for the chat history to delete
   * @throws Error if unable to delete chat history
   * @returns Promise that resolves when chat history is deleted
   */
  deleteChatHistory: (chatId: string) => Promise<boolean> | Promise<void>;
}

ChatHistoryStore interface has the following methods and properties:

history: A collection of chat histories.
addChatHistory: Adds a chat history to the store. Each element of the MessageData array represents a message in the chat history (with role and content).
updateChatHistory: Updates the chat history for a given chat ID. This overwrites the existing chat history with the new messages.
addMessages: Adds messages to the chat history for a given chat ID.
getChatHistory: Retrieves the chat history for a given chat ID.
deleteChatHistory: Deletes the chat history for a given chat ID.

Chat History Record

Each chat history record stored in a chat history store follows the structure below:

/**
 * Represents a record of chat history.
 */
export type ChatHistoryRecord = {
  messages: MessageData[];
  lastUpdated?: Date;
};

Providing Chat History Store to Chat Endpoint

You can provide an instance of a chat history store to the defineChatEndpoint function. The chat endpoint will use this store to manage chat histories.

import { InMemoryChatHistoryStore } from "@oconva/qvikchat/history";
 
// Open-ended chat endpoint with support for chat history
defineChatEndpoint({
  endpoint: "chat-open-history",
  enableChatHistory: true,
  chatHistoryStore: new InMemoryChatHistoryStore(),
});

Use Firebase Firestore as Chat History Store

You can use Firestore as a chat history store. To do this, you can provide an instance of the FirestoreChatHistoryStore class as the chatHistoryStore when configuring the chat endpoint using defineChatEndpoint function.

When creating an instance of the FirestoreChatHistoryStore class, you need to provide the following options:

firebaseApp: The Firebase app instance.
collectionName: The name of the collection that will store the chat history.

The collection storing the chat history will contain records that follow the structure of the ChatHistoryRecord type. For more information, check Chat History Record.

import { getFirebaseApp } from "@oconva/qvikchat/firebase";
import { FirestoreChatHistoryStore } from "@oconva/qvikchat/history";
import { defineChatEndpoint } from "@oconva/qvikchat/endpoints";
 
// Initialize Firebase App
const firebaseApp = getFirebaseApp();
 
// Firestore chat history store
const firestoreChatHistoryStore = new FirestoreChatHistoryStore({
  firebaseApp,
  collectionName: "chat-history", // collection that will store chat history
});
 
// Chat Endpoint with Firestore chat history store
defineChatEndpoint({
  endpoint: "chat",
  enableChatHistory: true,
  chatHistoryStore: firestoreChatHistoryStore,
});

Remember to initialize the Firebase app before using FirestoreCacheStore. To learn more about initializing the Firebase app, check Initialize Firebase App

Testing Endpoints Prompts