Trigger Webless from your site

Open the search experience and send custom browser events from your own UI.

This page covers the browser events you dispatch. For lifecycle events emitted by Webless itself, see Listen to Webless analytics events.

Install the widget

Add the Webless widget script to your site. Webless will provide the production script URL for your account.

<script src="YOUR_WIDGET_SCRIPT_URL"></script>

Open the search popup

Dispatch the webless-search event whenever a user clicks a custom button, link, or CTA.

search-trigger.js

document.dispatchEvent(new CustomEvent("webless-search"));

Send custom tracking events

Dispatch the webless-event custom event when you want to send additional tracking context into Webless analytics.

document.dispatchEvent(
  new CustomEvent("webless-event", {
    detail: {
      event_type: "search_button_click",
      page: window.location.pathname,
      query: "pricing",
      metadata: {
        placement: "header",
        campaign: "spring-launch"
      }
    }
  })
);

Event payload

Field	Required	Description
event_type	Yes	A short identifier for the event
page	No	The current page path
query	No	The active search query
metadata	No	Any additional structured details

Common pattern

Use one handler to track the click and open the widget in the same interaction.

document.getElementById("search-btn").addEventListener("click", () => {
  document.dispatchEvent(
    new CustomEvent("webless-event", {
      detail: {
        event_type: "search_button_click",
        page: window.location.pathname
      }
    })
  );

  document.dispatchEvent(new CustomEvent("webless-search"));
});

Keep event_type values stable and machine-readable. That makes downstream analytics, Clay enrichment, and internal dashboards much easier to maintain.