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
onAskAIHandoffOpen
onAskAIHandoffSubmit
onAskAIHandoffCancel
onModeSwitch
onSearchResultsCompleted
onSearchResultClick

Prerequisites

Before you can register event handlers, you need to preinitialize the global Kapa object.

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 Website 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.

onAskAIHandoffOpen

Triggered when the user presses the conversation handoff button, in every handoff mode. In email and custom-with-form mode the Kapa form opens at the same time. In custom mode nothing else happens: this event is the handoff, and your handler is expected to route the conversation into your own tool.

Kapa(
  "onAskAIHandoffOpen",
  ({ threadId, questionAnswerId, conversation, triggersMatched, transcript }) => {
    console.log("Handoff started.");
  },
);

Callback arguments:

Argument	Type	Description
threadId	string \| null	The thread ID of the current conversation.
questionAnswerId	string	The question-answer ID of the answer the button was pressed on.
conversation	Object[]	The full conversation history. A list of objects that each contain the `questionAnswerId`, `question` and `answer` of the question-answer pair.
triggersMatched	string[]	The triggers that caused the button to show for this answer. See Conversation handoff.
transcript	string	A markdown rendering of the whole conversation, including cited sources and user reactions, ready to paste into a ticket. See The transcript.

onAskAIHandoffSubmit

Triggered when the user submits Kapa's handoff form. This applies to email mode and custom-with-form mode; in custom mode there is no form and this event does not fire.

Email mode: fires after the email has been sent. Handlers are observers; if one throws or rejects, the error is logged to the console and the user still sees the success screen. Do not create a ticket from this handler in email mode, Kapa has already sent it.
custom-with-form mode: no email is sent and your handler is the action. The widget awaits every handler. If they all resolve the user sees the success screen; if one throws or rejects the user sees an error message with the form still filled in so they can retry. Return a promise from your handler so the form shows a loading state while your request is in flight.

The example below is for custom-with-form mode:

Kapa(
  "onAskAIHandoffSubmit",
  async ({
    threadId,
    questionAnswerId,
    conversation,
    triggersMatched,
    transcript,
    userEmail,
    note,
    noteLength,
  }) => {
    await createTicket({ email: userEmail, note, transcript, threadId });
  },
);

Callback arguments:

Argument	Type	Description
threadId	string \| null	The thread ID of the current conversation.
questionAnswerId	string	The question-answer ID of the answer the button was pressed on.
conversation	Object[]	The full conversation history. A list of objects that each contain the `questionAnswerId`, `question` and `answer` of the question-answer pair.
triggersMatched	string[]	The triggers that caused the button to show for this answer. See Conversation handoff.
transcript	string	A markdown rendering of the whole conversation, including cited sources and user reactions, ready to paste into a ticket. See The transcript.
userEmail	string	The email address the user entered in the form.
note	string \| undefined	The note the user entered in the form, or `undefined` when the user left it empty.
noteLength	number	Character length of the note (`0` if no note was provided).

onAskAIHandoffCancel

Triggered when the user closes the handoff form without submitting.

Kapa(
  "onAskAIHandoffCancel",
  ({ threadId, questionAnswerId, conversation }) => {
    console.log("Handoff cancelled.");
  },
);

Callback arguments:

Argument	Type	Description
threadId	string \| null	The thread ID of the current conversation.
questionAnswerId	string	The question-answer ID of the answer the button was opened from.
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`.

onSearchResultClick

Triggered when a search result is clicked.

Kapa("onSearchResultClick", ({ query, searchResult, rank }) => {
  console.log("Search result clicked: ", searchResult.title);
});

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.

Prerequisites​

Registering event handlers​

Example: Vanilla JavaScript​

Example: React​

Event types​

onModalOpen​

onModalClose​

onAskAIQuerySubmit​

onAskAIExampleQuerySubmit​

onAskAIAnswerCompleted​

onAskAIFeedbackSubmit​

onAskAILinkClick​

onAskAISourceClick​

onAskAIAnswerCopy​

onAskAIGenerationStop​

onAskAIConversationReset​

onAskAIHandoffOpen​

onAskAIHandoffSubmit​

onAskAIHandoffCancel​

onModeSwitch​

onSearchResultsCompleted​

onSearchResultClick​

Prerequisites

Registering event handlers

Example: Vanilla JavaScript

Example: React

Event types

onModalOpen

onModalClose

onAskAIQuerySubmit

onAskAIExampleQuerySubmit

onAskAIAnswerCompleted

onAskAIFeedbackSubmit

onAskAILinkClick

onAskAISourceClick

onAskAIAnswerCopy

onAskAIGenerationStop

onAskAIConversationReset

onAskAIHandoffOpen

onAskAIHandoffSubmit

onAskAIHandoffCancel

onModeSwitch

onSearchResultsCompleted

onSearchResultClick