Web Widget API

The kapa Web Widget API is a JavaScript API that exposes a set of functions to interact with the kapa widget.

Installation

The kapa JavaScript library provides a Kapa object that exposes the different widget functions. To make the 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>

Events API

The Events API allows for listening to certain events within the kapa Web Widget as well as consuming the data associated wih these events, by passing a callback function to the different methods.

This is helpful if you want to track kapa usage in your analytics stack such as tracking submitted questions in tools like Mixpanel, Amplitude, Segment, etc.

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 Usage

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

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

React example:

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.

Web Widget API

Installation​

Events API​

Example Usage​

Event Types​

onModalOpen​

onModalClose​

onAskAIQuerySubmit​

onAskAIExampleQuerySubmit​

onAskAIAnswerCompleted​

onAskAIFeedbackSubmit​

onAskAILinkClick​

onAskAISourceClick​

onAskAIAnswerCopy​

onAskAIGenerationStop​

onAskAIConversationReset​

onModeSwitch​

onSearchResultsCompleted​

onSearchResultsShowMoreClick​

onSearchResultClick​

Installation

Events API

Example Usage

Event Types

onModalOpen

onModalClose

onAskAIQuerySubmit

onAskAIExampleQuerySubmit

onAskAIAnswerCompleted

onAskAIFeedbackSubmit

onAskAILinkClick

onAskAISourceClick

onAskAIAnswerCopy

onAskAIGenerationStop

onAskAIConversationReset

onModeSwitch

onSearchResultsCompleted

onSearchResultsShowMoreClick

onSearchResultClick