Webless Analytics Events Guide

When using Webless FE Tag

How to listen to events emitted by Webless

Webless emits browser CustomEvents on document for key user interactions. Event names follow the pattern webless:{eventType} and include a JSON payload under event.detail.

The event types you can listen to:

1. session_start

Disptached when the tab opens and the Webless tag loads
Fields:
- session_id: string :: The UUID which was generated for this session

2. searchbar_visible

Disptached when the Searchbar is visible
Fields:
- session_id: string :: The UUID which was generated for this session

3. search_input

Disptached whenever the user clicks on the Searchbar or the Searchbar is in focus
Fields:
- session_id: string :: The UUID which was generated for this session

4. searchbar_click

Dispatched when the user has typed a question and clicked on search icon or pressed ENTER
Fields:
- session_id: string :: The UUID which was generated for this session
- query : string :: The question that was asked by the user
- request_id: string :: The UUID which was generated for this query

5. suggested_question_click

Dispatched when the user clicks on a suggested question
Fields:
- session_id: string :: The UUID which was generated for this session
- query : string :: The suggested question that was clicked by the user
- request_id: string :: The UUID which was generated for this query

6. related_question_click

Dispatched when the user clicks on any one of the 3 related question shown at the end of the Modal
Fields:
- session_id: string :: The UUID which was generated for this session
- query : string :: The realated question that was clicked by the user
- request_id: string :: The UUID which was generated for this query

7. tile_click

Dispatched when the user clicks on a tile in the related content section
Fields:
- session_id: string :: The UUID which was generated for this session
- query : string :: The question for which this tile was shown as a response
- request_id: string :: The UUID which was generated for this query
- tile_id: string :: The URL of the tile which was clicked

8. click_cta

Dispatched when the user clicks on the CTA Button
Fields:
- session_id: string :: The UUID which was generated for this session
- query : string :: The question for which this CTA was shown as a response
- request_id: string :: The UUID which was generated for this query
- cta_text: string :: The text of the CTA which was clicked

9. cta_form

Dispatched when the user submits the embedded CTA Form
NOTE: If there is no embedded CTA Form, this event will NOT be dispatched

10. gated_form

Dispatched when the user submits the embedded Gated Form
NOTE: If there is no gated content and no gated embedded Form, this event will NOT be dispatched

Listen to a single event:

<script>
  document.addEventListener("webless:tile_click", function (ev) {
    const payload = ev && ev.detail; // { eventType, timestamp, ...custom fields }
    console.log("Webless tile_click:", payload);
  });

  // Example: search input
  document.addEventListener("webless:search_input", function (ev) {
    console.log("User typed in search:", ev.detail);
  });
</script>

Listen to multiple events with one helper:

<script>
  (function () {
    var EVENT_TYPES = [
      "session_start",
      "searchbar_visible",
      "search_input",
      "searchbar_click",
      "suggested_question_click",
      "related_question_click",
      "tile_click",
      "click_cta",
      "cta_form",
      "gated_form",
    ];

    EVENT_TYPES.forEach(function (type) {
      document.addEventListener("webless:" + type, function (ev) {
        var payload = (ev && ev.detail) || {};
        console.log("Webless event:", type, payload);
      });
    });
  })();
</script>

Payload shape:

type WeblessClientEvent = {
  eventType: string; // e.g., "tile_click"
  timestamp: number; // ms since epoch
  // plus additional keys depending on event (e.g., query, tile_id, gated, request_id, etc.)
  [key: string]: unknown;
};

How to send to 3rd party (like Amplitude)

Initialize Amplitude (or any 3rd party), then forward Webless events:

<script src="https://cdn.amplitude.com/libs/amplitude-8.20.4-min.gz.js"></script>
<script>
  amplitude.getInstance().init("YOUR_AMPLITUDE_API_KEY");

  var FORWARDED_EVENTS = [
    "tile_click",
    "click_cta",
    "suggested_question_click",
    "related_question_click",
    "searchbar_click",
    "search_input",
  ];

  FORWARDED_EVENTS.forEach(function (type) {
    document.addEventListener("webless:" + type, function (ev) {
      var payload = (ev && ev.detail) || {};
      // Use the raw type or prefix with "webless:" as your naming convention
      amplitude.getInstance().logEvent(type, payload);
    });
  });
</script>

Tip: If you need to throttle high-volume events (like search_input), debounce before forwarding.

When using Webless API

How to send to Webless

Send a POST request to Webless’s event capture endpoint at /event with a JSON body.

Staging URL: https://d24luoisenoi7j.cloudfront.net/staging/event
Production URL: https://d24luoisenoi7j.cloudfront.net/event

Event types and payloads

Below is a complete list of supported event_type values, the fields we send for each, and an example payload. Unless noted otherwise, each event includes these base fields:

Field	Type	Description
`event_type`	string	The event type for the interaction that is happening
`page`	string	The current URL of the page
`timestamp`	number	The epoch timestamp in milliseconds
`session_id`	string	The session-id that was generated for this session
`company`	string	The company index identifier that was shared with you
`location`	"floating" or "nav"	Location of the Searchbar in your design (usually "floating")

1. session_start

Sent as soon as the page or tab loads
Extra fields: None
Example:

{
  "event_type": "session_start",
  "page": "https://example.com",
  "timestamp": 1730000000000,
  "session_id": "SESSION_ID",
  "company": "COMPANY_INDEX",
  "location": "floating"
}

2. searchbar_visible

Sent once the searchbar is visible.
Extra fields: None
Example:

{
  "event_type": "searchbar_visible",
  "page": "https://example.com",
  "timestamp": 1730000000000,
  "session_id": "SESSION_ID",
  "company": "COMPANY_INDEX",
  "location": "floating"
}

3. search_input

Sent whenever the user clicks on the searchbar
Extra Fields: None
Example:

{
  "event_type": "search_input",
  "page": "https://example.com",
  "timestamp": 1730000000000,
  "session_id": "SESSION_ID",
  "company": "COMPANY_INDEX",
  "location": "floating"
}

4. searchbar_click

Sent when the user has clicked on the search icon or pressed ENTER after typing their question
Extra Fields

Field	Type	Description
`query`	string	The question that the user was asked
`request_id`	string	The request identifier that was generated for this question

Example:

{
  "event_type": "searchbar_click",
  "page": "https://example.com",
  "timestamp": 1730000000000,
  "session_id": "SESSION_ID",
  "company": "COMPANY_INDEX",
  "location": "floating",
  "query": "reset password",
  "request_id": "REQUEST_ID"
}

5. suggested_question_click

Sent when the user clicks on a suggested question
Extra Fields

Field	Type	Description
`query`	string	The suggested question that the user clicked on
`request_id`	string	The request identifier that was generated for this question

Example:

{
  "event_type": "suggested_question_click",
  "page": "https://example.com",
  "timestamp": 1730000000000,
  "session_id": "SESSION_ID",
  "company": "COMPANY_INDEX",
  "location": "floating",
  "query": "how to change email",
  "request_id": "REQUEST_ID"
}

6. related_question_click

Sent when the user clicks on a related questions. These are the 3 questions that are shown at the end of the Modal
Extra Fields

Field	Type	Description
`query`	string	The related question that the user clicked on
`request_id`	string	The request identifier that was generated for this question

Example:

{
  "event_type": "related_question_click",
  "page": "https://example.com",
  "timestamp": 1730000000000,
  "session_id": "SESSION_ID",
  "company": "COMPANY_INDEX",
  "location": "floating",
  "query": "account recovery options",
  "request_id": "REQUEST_ID"
}

7. tile_click

Sent when the user clicks on a tile
Extra Fields

Field	Type	Description
`query`	string	The question that the user asked
`request_id`	string	The request identifier which was generated for this question
`tile_id`	string	The tile URL that was clicked by the user
`gated`	"1" or "0"	Whether the tile is gated ("1") or not ("0"). Always "0" if there is no gated content

Example:

{
  "event_type": "tile_click",
  "page": "https://example.com",
  "timestamp": 1730000000000,
  "session_id": "SESSION_ID",
  "company": "COMPANY_INDEX",
  "location": "floating",
  "query": "reset password",
  "request_id": "REQUEST_ID",
  "tile_id": "TILE_ID",
  "gated": "0"
}

8. click_cta

Sent when the user clicks on the CTA button
Extra Fields

Field	Type	Description
`query`	string	The question that the user asked
`request_id`	string	The request identifier that was generated for this question
`cta_message`	string	The text that is displayed on the CTA
`open_type`	"blank" or "form"	Usually "blank". Use "form" ONLY when there is an embedded form in your experience

Example:

{
  "event_type": "click_cta",
  "page": "https://example.com",
  "timestamp": 1730000000000,
  "session_id": "SESSION_ID",
  "company": "COMPANY_INDEX",
  "location": "floating",
  "query": "reset password",
  "request_id": "REQUEST_ID",
  "cta_message": "Open support portal",
  "open_type": "blank"
}

9. cta_form

Sent when the CTA form is submitted. NOTE: If there is no embedded CTA form, then there is no need to send this event
Extra Fields

Field	Type	Description
`query`	string	The question that led to the CTA button being clicked and CTA form being opened
`request_id`	string	The request identifier that was generated for this question
`cta_message`	string	The text on the CTA button which was clicked
`open_type`	"blank" or "form"	For forms this will be "form"
`form_submit`	"1" or "0"	Whether the user submitted the form ("1") or not ("0")

Example:

{
  "event_type": "cta_form",
  "page": "https://example.com",
  "timestamp": 1730000000000,
  "session_id": "SESSION_ID",
  "company": "COMPANY_INDEX",
  "location": "floating",
  "query": "billing support",
  "request_id": "REQUEST_ID",
  "cta_message": "Get a demo",
  "open_type": "blank",
  "form_submit": "1"
}

10. gated_form

Sent when a Gated form is submitted. NOTE: If there is no embedded Gated form, then there is no need to send this event
Extra Fields

Field	Type	Description
`query`	string	The question that led to the CTA button being clicked and CTA form being opened
`request_id`	string	The request identifier that was generated for this question
`form_submit`	"1" or "0"	Whether the user submitted the form

Example:

{
  "event_type": "gated_form",
  "page": "https://example.com",
  "timestamp": 1730000000000,
  "session_id": "SESSION_ID",
  "company": "COMPANY_INDEX",
  "location": "floating",
  "query": "whitepaper download",
  "request_id": "REQUEST_ID",
  "form_submit": "0"
}

Webless Events Guide

Complete reference for Webless browser events and API event payloads, including when each event fires and the fields sent.

Webless Analytics Events Guide

On this page

When using Webless FE Tag

How to listen to events emitted by Webless

1. session_start

2. searchbar_visible

3. search_input

4. searchbar_click

5. suggested_question_click

6. related_question_click

7. tile_click

8. click_cta

9. cta_form

10. gated_form

How to send to 3rd party (like Amplitude)

When using Webless API

How to send to Webless

Event types and payloads

1. session_start

2. searchbar_visible

3. search_input

4. searchbar_click

5. suggested_question_click

6. related_question_click

7. tile_click

8. click_cta

9. cta_form

10. gated_form