Events

The website widget allows you to register event handlers via the window.Kapa object to listen to events. This can be helpful if you want to track widget interactions in your own analytics tools like Amplitude, Mixpanel or Segment.

Event handlers can be registered for the following event types:

onModalOpen
onModalClose
onAskAIQuerySubmit
onAskAIExampleQuerySubmit
onAskAIAnswerCompleted
onAskAIFeedbackSubmit
onAskAILinkClick
onAskAISourceClick
onAskAIAnswerCopy
onAskAIGenerationStop
onAskAIConversationReset
onModeSwitch
onSearchResultsCompleted
onSearchResultsShowMoreClick
onSearchResultClick

Setup

You need to complete the following setup before registering event handlers:

To make the window.Kapa object available, copy and paste the JavaScript snippet below inside a </script> before the </body> tag on every page where you are currently rendering the Kapa Web Widget.

(function () {
  let k = window.Kapa;
  if (!k) {
    let i = function () {
      i.c(arguments);
    };
    i.q = [];
    i.c = function (args) {
      i.q.push(args);
    };
    window.Kapa = i;
  }
})();

In a simple HTML page, you can paste it into the page </head> like this:

<head>
  <script>
    (function () {
      let k = window.Kapa;
      if (!k) {
        let i = function () {
          i.c(arguments);
        };
        i.q = [];
        i.c = function (args) {
          i.q.push(args);
        };
        window.Kapa = i;
      }
    })();
  </script>
</head>
<body>
  ...
</body>

Registering event handlers

Event listeners can be registered with the Kapa function object, by providing the following arguments:

The widget event type (e.g. onAskAIQuerySubmit)
An event handler
An optional option parameter which can be set to add (default) or remove. This is relevant for clean-up actions such as in lifecycle, like useEffect methods in React.

Example: Vanilla JavaScript

// Adding an event listener
Kapa("onAskAIQuerySubmit", function (args) {
  /* do something */
});

// Removing an event listener
Kapa(
  "onAskAIQuerySubmit",
  function (args) {
    /* do something */
  },
  "remove",
);

Example: React

useEffect(() => {
  const handler = (args) => { console.log("Query submitted."); },
  Kapa(
    "onAskAIQuerySubmit",
    handler,
    "add" // The 'add' option is optional and can be omitted
  );

  return () => Kapa("onAskAIQuerySubmit", handler, "remove");
});

Event types

List of available Kapa widget events.

onModalOpen

Triggered when the widget modal is opened.

Kapa("onModalOpen", function ({ mode }) {
  console.log("Modal opened.");
});

Callback arguments:

Argument	Type	Description
`mode`	string	The mode the widget is set to when the modal is opened. Can be `search` or `ai`.

onModalClose

Triggered when the widget modal is closed.

Kapa("onModalClose", function ({ mode }) {
  console.log("Modal closed.");
});

Callback arguments:

Argument	Type	Description
mode	string	The mode the widget is set to when the modal is closed. Can be `search` or `ai`.

onAskAIQuerySubmit

Triggered when a user submits an Ask AI query.

Kapa("onAskAIQuerySubmit", ({ threadId, questionAnswerId, question }) => {
  console.log("Query submitted.");
});

Callback arguments:

Argument	Type	Description
threadId	string \| null	The thread ID of the current conversation. This is created after the answer to the first question in the conversation is completed.
questionAnswerId	string	The question-answer ID of the current question-answer pair. This is created when the user submits a question.
question	string	The submitted question.

onAskAIExampleQuerySubmit

Triggered when a user submits an Ask AI query from the list of example questions, if enabled.

Kapa(
  "onAskAIExampleQuerySubmit",
  ({ threadId, questionAnswerId, question }) => {
    console.log("Example query submitted.");
  },
);

Callback arguments:

Argument	Type	Description
threadId	string \| null	The thread ID of the current conversation. This is created after the answer to the first question in the conversation is completed.
questionAnswerId	string	The question-answer ID of the current question-answer pair. This is created when the user submits a question.
question	string	The submitted question.

onAskAIAnswerCompleted

Triggered when a Kapa answer to a question is completed.

Kapa(
  "onAskAIAnswerCompleted",
  ({ threadId, questionAnswerId, question, answer, conversation }) => {
    console.log("Answer completed.");
  },
);

Callback arguments:

Argument	Type	Description
threadId	string	The thread ID of the current conversation. This is created after the answer to the first question in the conversation is completed.
questionAnswerId	string	The question-answer ID of the current question-answer pair. This is created when the user submits a question.
question	string	The submitted question.
answer	string	The Kapa answer.
conversation	Object[]	The full conversation history. A list of objects that each contain the `questionAnswerId`, `question` and `answer` of the question-answer pair.

onAskAIFeedbackSubmit

Triggered when feedback to an answer is submitted. Note that this event is also triggered when the user changes their feedback for a certain answer.

Kapa(
  "onAskAIFeedbackSubmit",
  ({
    reaction,
    comment,
    threadId,
    questionAnswerId,
    question,
    answer,
    conversation,
  }) => {
    console.log("Feedback submitted.");
  },
);

Callback arguments:

Argument	Type	Description
reaction	string	The feedback reaction. Can be `upvote` or `downvote`.
comment	Object	Additional comment added by the user. This is an object with the properties `issue` (a string comment), `irrelevant` (bool), `incorrect` (bool), `unaddressed` (bool).
threadId	string	The thread ID of the current conversation. This is created after the answer to the first question in the conversation is completed.
questionAnswerId	string	The question-answer ID of the current question-answer pair. This is created when the user submits a question.
question	string	The submitted question.
answer	string	The Kapa answer.
conversation	Object[]	The full conversation history. A list of objects that each contain the `questionAnswerId`, `question` and `answer` of the question-answer pair.

onAskAILinkClick

Triggered when a link inside the answer text is clicked.

Kapa(
  "onAskAILinkClick",
  ({ href, threadId, questionAnswerId, question, answer }) => {
    console.log("Link clicked.");
  },
);

Callback arguments:

Argument	Type	Description
href	string	The href / url of the clicked link.
threadId	string	The thread ID of the current conversation. This is created after the answer to the first question in the conversation is completed.
questionAnswerId	string	The question-answer ID of the current question-answer pair. This is created when the user submits a question.
question	string	The submitted question.
answer	string	The Kapa answer.

onAskAISourceClick

Triggered when one of the listed relevant sources for an answer is clicked.

Kapa(
  "onAskAISourceClick",
  ({ source, threadId, questionAnswerId, question, answer }) => {
    console.log("Source clicked.");
  },
);

Callback arguments:

Argument	Type	Description
source	Object	The source object. Contains the properties `title`, `subtitle` and `url`.
threadId	string	The thread ID of the current conversation. This is created after the answer to the first question in the conversation is completed.
questionAnswerId	string	The question-answer ID of the current question-answer pair. This is created when the user submits a question.
question	string	The submitted question.
answer	string	The Kapa answer.

onAskAIAnswerCopy

Triggered when an answer is copied to the clipboard.

Kapa(
  "onAskAIAnswerCopy",
  ({ threadId, questionAnswerId, question, answer }) => {
    console.log("Answer copied.");
  },
);

Callback arguments:

Argument	Type	Description
threadId	string	The thread ID of the current conversation. This is created after the answer to the first question in the conversation is completed.
questionAnswerId	string	The question-answer ID of the current question-answer pair. This is created when the user submits a question.
question	string	The submitted question.
answer	string	The Kapa answer.

onAskAIGenerationStop

Triggered when an answer generation is stopped.

Kapa("onAskAIGenerationStop", ({ threadId, question, conversation }) => {
  console.log("Answer generation stopped.");
});

Callback arguments:

Argument	Type	Description
threadId	string \| null	The thread ID of the current conversation. This is created after the answer to the first question in the conversation is completed.
question	string	The submitted question.
conversation	Object[]	The full conversation history. A list of objects that each contain the `questionAnswerId`, `question` and `answer` of the question-answer pair.

onAskAIConversationReset

Triggered when a conversation history is cleared.

Kapa("onAskAIConversationReset", ({ threadId, conversation }) => {
  console.log("Conversation reset.");
});

Callback arguments:

Argument	Type	Description
threadId	string	The thread ID of the current conversation. This is created after the answer to the first question in the conversation is completed.
conversation	Object[]	The full conversation history. A list of objects that each contain the `questionAnswerId`, `question` and `answer` of the question-answer pair.

onModeSwitch

Triggered when the mode in the widget is switched, if multiple modes are enabled.

Kapa("onModeSwitch", ({ mode }) => {
  console.log("Mode switched.");
});

Callback arguments:

Argument	Type	Description
mode	string	The mode the widget was switched to. Can be `'ai'` or `'search'`.

onSearchResultsCompleted

Triggered when a list of results is returned from a search request.

Kapa("onSearchResultsCompleted", ({ query, searchResults }) => {
  console.log("Search results completed.");
});

Callback arguments:

Argument	Type	Description
query	string	The search query.
searchResults	Object[]	The list of search result objects. Each object contains the properties `title`, `subtitle`, `url`, `sourceName`.

onSearchResultsShowMoreClick

Triggered when 'Show More' search results is clicked.

Kapa("onSearchResultsShowMoreClick", ({ query, searchResults }) => {
  console.log("Show more clicked.");
});

Callback arguments:

Argument	Type	Description
query	string	The search query.
searchResults	Object[]	The list of search result objects. Each object contains the properties `title`, `subtitle`, `url`, `sourceName`.

onSearchResultClick

Triggered when a search result is clicked.

Kapa("onSearchResultClick", ({ query, searchResult, rank }) => {
  console.log("Show more clicked.");
});

Callback arguments:

Argument	Type	Description
query	string	The search query.
searchResult	Object	The search result object. Contains the properties `title`, `subtitle`, `url`, `sourceName`.
rank	number	The rank of the search result in the list of all results.

Setup​

Registering event handlers​

Example: Vanilla JavaScript​

Example: React​

Event types​

onModalOpen​

onModalClose​

onAskAIQuerySubmit​

onAskAIExampleQuerySubmit​

onAskAIAnswerCompleted​

onAskAIFeedbackSubmit​

onAskAILinkClick​

onAskAISourceClick​

onAskAIAnswerCopy​

onAskAIGenerationStop​

onAskAIConversationReset​

onModeSwitch​

onSearchResultsCompleted​

onSearchResultsShowMoreClick​

onSearchResultClick​

Setup

Registering event handlers

Example: Vanilla JavaScript

Example: React

Event types

onModalOpen

onModalClose

onAskAIQuerySubmit

onAskAIExampleQuerySubmit

onAskAIAnswerCompleted

onAskAIFeedbackSubmit

onAskAILinkClick

onAskAISourceClick

onAskAIAnswerCopy

onAskAIGenerationStop

onAskAIConversationReset

onModeSwitch

onSearchResultsCompleted

onSearchResultsShowMoreClick

onSearchResultClick