---
name: kimaai:chatbot
type: js-event
since: 1.6.0
tier: free
feature: chatbot
area: chatbot
summary: A browser event for analytics and Google Tag Manager when a visitor opens the chat, sends a message, gets an answer, rates, clicks a link or a quick action, or sends a lead form.
parameters:
  - name: detail
    type: Object
    description: The event's detail.
  - name: detail.type
    type: string
    description: The moment, one of the types under "When it fires".
  - name: detail.sessionId
    type: string
    description: The conversation's session ID, the one the PHP hooks get; empty while the conversation has none.
  - name: detail.rating
    type: number
    description: For feedback only, 1 (helpful) or -1 (not helpful) for an answer, 1 to 5 for the conversation.
  - name: detail.kind
    type: string
    description: For feedback only, message for the rating of an answer, csat for the rating of the conversation.
  - name: detail.via
    type: string
    description: 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.
  - name: detail.visitorMessages
    type: number
    description: For close and restore, the visitor's messages in the conversation. Since 1.6.1.
  - name: detail.botMessages
    type: number
    description: For close and restore, the chatbot's answers in the conversation, without failed ones. Since 1.6.1.
  - name: detail.number
    type: number|null
    description: 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.
  - name: detail.characters
    type: number
    description: For message and answer, the length of the text in characters. Since 1.6.1.
  - name: detail.words
    type: number
    description: For message only, the number of words. Since 1.6.1.
  - name: detail.label
    type: string
    description: For quick_action only, the quick action's label as the site set it. Since 1.6.1.
  - name: detail.url
    type: string
    description: For link only, the link's full address. Since 1.6.1.
  - name: detail.text
    type: string
    description: For link only, the link's text. Since 1.6.1.
  - name: detail.from
    type: string
    description: 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.
  - name: detail.fullscreen
    type: boolean
    description: For fullscreen only, true when the larger window was switched on, false when it was switched off. Since 1.6.1.
  - name: detail.formId
    type: number
    description: For form only, the Gravity Forms form's ID. Since 1.6.1.
surfaces: [chatbot, search]
---

# 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:

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

## Example

```js
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`:

```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:

```js
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.
