Skip to main content
Webless emits DOM custom events with the webless: prefix and a structured event.detail payload.

​
Add listeners after Webless initializes

const eventTypes = [
  "session_start",
  "searchbar_visible",
  "searchbar_hidden",
  "searchbar_close",
  "searchbar_click",
  "suggested_question_click",
  "tile_click",
  "click_cta",
  "floating_button_visible",
  "floating_button_click"
];

eventTypes.forEach((eventType) => {
  document.addEventListener(`webless:${eventType}`, (event) => {
    console.log(`[Webless Event: ${eventType}]`, event.detail);

    // Forward to your analytics service here.
    // analytics.track(eventType, event.detail);
  });
});

​
Supported events

EventFired whenCore fields
webless:session_startA new user session startssessionId, timeStamp, eventType
EventFired whenCore fields
webless:searchbar_visibleThe search bar enters the viewportsessionId, location, timeStamp, eventType
webless:searchbar_hiddenThe search bar leaves the viewportsessionId, location, timeStamp, eventType
webless:searchbar_closeA user closes the floating search barsessionId, location, timeStamp, eventType
EventFired whenCore fields
webless:searchbar_clickA user submits a search queryquery, sessionId, timeStamp, eventType
webless:suggested_question_clickA user clicks a suggested questionquery, sessionId, timeStamp, eventType
webless:tile_clickA user clicks a result tilequery, sessionId, timeStamp, eventType
webless:click_ctaA user clicks the CTA buttonquery, sessionId, timeStamp, eventType
EventFired whenCore fields
webless:floating_button_visibleThe floating button enters the viewportsessionId, location, timeStamp, eventType
webless:floating_button_clickA user clicks the floating buttonsessionId, location, timeStamp, eventType

​
Payload shape

interface ClientEventPayload {
  eventType: string;
  timeStamp: number;
  sessionId: string;
  location?: "floating" | "nav";
  query?: string;
  [key: string]: unknown;
}

​
Example payloads

{
  "sessionId": "abc123-def456-ghi789",
  "timeStamp": 1703123456789,
  "eventType": "session_start"
}

​
Performance and troubleshooting

  • Make sure Webless finished initializing before you add listeners.
  • Make sure your listener script appears after the Webless script.
  • Make sure no browser console errors stop later scripts from running.
Debounce frequent events before forwarding them to your analytics service.
const debounce = (fn, wait) => {
  let timeout;
  return (...args) => {
    clearTimeout(timeout);
    timeout = setTimeout(() => fn(...args), wait);
  };
};

const debouncedTrack = debounce((eventName, data) => {
  analytics.track(eventName, data);
}, 1000);