Events
You can use the Web Widget Events API to listen to cetain events within the kapa Web Widget as well as consume the data associated wih these events. This can be helpful if you want to track widget interactions in your own analytics tools like Amplitude, Mixpanel or Segment.
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
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 toadd
(default) orremove
. This is relevant for clean-up actions such as in lifecycle, likeuseEffect
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. |