kimaai:chatbot

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:

TypeWhenFieldsSince
openThe floating chat’s window opened.via (since 1.6.1)1.6.0
closeThe 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
messageThe visitor sent a message, typed or from a quick action.number, characters, words (since 1.6.1)1.6.0
answerAn 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
feedbackA rating was saved, of an answer (kind message) or of the conversation (kind csat).rating, kind1.6.0
leadThe visitor sent the lead form (Pro).1.6.0
welcomeThe welcome of a new conversation shows, once the chat knows there is no earlier one.1.6.1
restoreAn earlier conversation shows again when the chat loads it.visitorMessages, botMessages1.6.1
quick_actionThe visitor clicked a quick action: in the welcome, after an answer or in the attention popover.label1.6.1
linkThe visitor clicked a link in the chat window.url, text, from1.6.1
fullscreenThe visitor switched the larger window on or off.fullscreen1.6.1
consent_showThe consent box shows, because the site asks for consent and the visitor has not given it.1.6.1
consent_acceptThe visitor accepted the consent.1.6.1
popover_showThe attention popover beside the launcher shows.1.6.1
popover_dismissThe visitor closed the attention popover.1.6.1
formA Gravity Forms form shows in an answer.formId1.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

NameTypeDescription
detailObjectThe event’s detail.
detail.typestringThe moment, one of the types under “When it fires”.
detail.sessionIdstringThe conversation’s session ID, the one the PHP hooks get; empty while the conversation has none.
detail.ratingnumberFor feedback only, 1 (helpful) or -1 (not helpful) for an answer, 1 to 5 for the conversation.
detail.kindstringFor feedback only, message for the rating of an answer, csat for the rating of the conversation.
detail.viastringFor 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.visitorMessagesnumberFor close and restore, the visitor’s messages in the conversation. Since 1.6.1.
detail.botMessagesnumberFor close and restore, the chatbot’s answers in the conversation, without failed ones. Since 1.6.1.
detail.numbernumber|nullFor 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.charactersnumberFor message and answer, the length of the text in characters. Since 1.6.1.
detail.wordsnumberFor message only, the number of words. Since 1.6.1.
detail.labelstringFor quick_action only, the quick action’s label as the site set it. Since 1.6.1.
detail.urlstringFor link only, the link’s full address. Since 1.6.1.
detail.textstringFor link only, the link’s text. Since 1.6.1.
detail.fromstringFor 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.fullscreenbooleanFor fullscreen only, true when the larger window was switched on, false when it was switched off. Since 1.6.1.
detail.formIdnumberFor 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.
  }
});
  • 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.

What are your feelings