When it fires
In the visitor’s browser, on the chat root (#kimaai-chatbot for the floating chat, an element with data-kimaai-chatbot for an inline chat, the Ask AI dialog and the search answer). The widget renders inside a shadow root on that element; the event is sent on the element itself, bubbles and is composed, so listeners on document and on window get it, and event.target is the chat root.
Every event has type and sessionId. The types and the fields they add:
| Type | When | Fields | Since |
|---|---|---|---|
open | The floating chat’s window opened. | via (since 1.6.1) | 1.6.0 |
close | The floating chat’s window closed, after the rating at the end if one was asked for. | via, visitorMessages, botMessages (since 1.6.1) | 1.6.0 |
message | The visitor sent a message, typed or from a quick action. | number, characters, words (since 1.6.1) | 1.6.0 |
answer | An answer arrived and is shown, streamed or not; not when it failed or the visitor stopped it. | number, characters (since 1.6.1) | 1.6.0 |
feedback | A rating was saved, of an answer (kind message) or of the conversation (kind csat). | rating, kind | 1.6.0 |
lead | The visitor sent the lead form (Pro). | 1.6.0 | |
welcome | The welcome of a new conversation shows, once the chat knows there is no earlier one. | 1.6.1 | |
restore | An earlier conversation shows again when the chat loads it. | visitorMessages, botMessages | 1.6.1 |
quick_action | The visitor clicked a quick action: in the welcome, after an answer or in the attention popover. | label | 1.6.1 |
link | The visitor clicked a link in the chat window. | url, text, from | 1.6.1 |
fullscreen | The visitor switched the larger window on or off. | fullscreen | 1.6.1 |
consent_show | The consent box shows, because the site asks for consent and the visitor has not given it. | 1.6.1 | |
consent_accept | The visitor accepted the consent. | 1.6.1 | |
popover_show | The attention popover beside the launcher shows. | 1.6.1 | |
popover_dismiss | The visitor closed the attention popover. | 1.6.1 | |
form | A Gravity Forms form shows in an answer. | formId | 1.6.1 |
Only the floating chat sends open, close and the popover’s events: an inline chat is always open, and the Ask AI dialog sends neither. The floating chat loads its conversation each time its window opens, so welcome, restore and form come again with each opening. A quick action click is sent even while the consent still waits, when the click only points to the consent box. The search answer box sends feedback for the rating under its answer and quick_action for its quick actions. The admin assistant sends nothing; the chat preview in the KimaAI settings sends the events of a chat, on the admin page.
The detail never holds what the visitor typed or entered in a form: a message is told by its number and length only, and a link in the visitor’s own message sends no link event. Labels, link texts and addresses are the site’s and the chatbot’s content. sessionId is empty until the chat knows its conversation: the floating chat learns it from the conversation’s history once the window is open, or with the first answer of a new visitor, so the first open of a page view carries none; an inline chat knows it from the start.
Parameters
| Name | Type | Description |
|---|---|---|
detail | Object | The event’s detail. |
detail.type | string | The moment, one of the types under “When it fires”. |
detail.sessionId | string | The conversation’s session ID, the one the PHP hooks get; empty while the conversation has none. |
detail.rating | number | For feedback only, 1 (helpful) or -1 (not helpful) for an answer, 1 to 5 for the conversation. |
detail.kind | string | For feedback only, message for the rating of an answer, csat for the rating of the conversation. |
detail.via | string | For open, how the window opened (launcher or popover; empty when it opened by itself, as in the settings preview). For close, how it closed (button, launcher or escape). Since 1.6.1. |
detail.visitorMessages | number | For close and restore, the visitor’s messages in the conversation. Since 1.6.1. |
detail.botMessages | number | For close and restore, the chatbot’s answers in the conversation, without failed ones. Since 1.6.1. |
detail.number | number|null | For message, the message’s number in the conversation (1 for the first); null when the visitor sent it before the chat had loaded the conversation. For answer, the number of the message it answers. Since 1.6.1. |
detail.characters | number | For message and answer, the length of the text in characters. Since 1.6.1. |
detail.words | number | For message only, the number of words. Since 1.6.1. |
detail.label | string | For quick_action only, the quick action’s label as the site set it. Since 1.6.1. |
detail.url | string | For link only, the link’s full address. Since 1.6.1. |
detail.text | string | For link only, the link’s text. Since 1.6.1. |
detail.from | string | For link only, where the link was, answer (the text of an answer), card (a card in an answer, such as a product or a ticket), sources (the sources view) or other (the welcome, the consent text). Since 1.6.1. |
detail.fullscreen | boolean | For fullscreen only, true when the larger window was switched on, false when it was switched off. Since 1.6.1. |
detail.formId | number | For form only, the Gravity Forms form’s ID. Since 1.6.1. |
Example
document.addEventListener('kimaai:chatbot', function (event) {
var data = {event: 'kimaai_chat_' + event.detail.type};
for (var key in event.detail) {
if (key !== 'type') {
data['kimaai_' + key] = event.detail[key];
}
}
window.dataLayer = window.dataLayer || [];
window.dataLayer.push(data);
});
The listener hands each moment to Google Tag Manager as a data layer event, with each field of the detail as a data layer variable: kimaai_chat_open with kimaai_via, kimaai_chat_message with kimaai_number, kimaai_characters and kimaai_words, kimaai_chat_link with kimaai_url, kimaai_text and kimaai_from, and so on. Load it with your theme’s scripts, or put it in a Custom HTML tag (inside a script element) that fires on all pages; it uses no newer JavaScript syntax, so it runs there too. In Tag Manager, a Custom Event trigger with the event name kimaai_chat_.* (use regex matching) catches them all, and Data Layer Variables read the fields, such as kimaai_rating and kimaai_kind.
More examples
Straight to Google Analytics 4, on a site that loads gtag.js:
window.addEventListener('kimaai:chatbot', (event) => {
if (typeof window.gtag !== 'function') {
return;
}
const {type, ...fields} = event.detail;
window.gtag('event', `chatbot_${type}`, fields);
});
Only the floating chat, by its chat root:
document.addEventListener('kimaai:chatbot', (event) => {
if (event.target.id === 'kimaai-chatbot' && event.detail.type === 'open' && event.detail.via === 'popover') {
// The visitor opened the floating chat from the attention popover.
}
});
Related
kimaai_chatbot_after_response: the answer on the server, with its text.kimaai_chatbot_message_feedback_saved: an answer’s rating on the server.kimaai_chatbot_csat_saved: the conversation’s rating on the server.