Overview

Conversational Assistant Tracking Overview

🚧

Beta Release

These tracking events are currently in beta and are subject to change. Like the rest of the Conversational Assistant API, event names, payloads, and behavior may change before general availability.

This guide covers how to send tracking events for the Conversational Assistant using the Athos Beacon API.

Shopper interactions with products shown in the chat must be reported to Athos analytics. All events require a context object (see Context Object Guide) and event-specific data.

Base URL: https://analytics.athoscommerce.net/beacon/v2/{siteId}/chat/[event]

📘

Note

{siteId} and [event] should be replaced with your site's siteId, found in your Athos management console, and the subsequent event.


1. Load Beacon

The easiest way to send these events is with Beacon.js.

  • CDN: add <script src="https://cdn.athoscommerce.net/analytics/beacon.js" siteId="YOUR_SITE_ID"></script> before </head>. It initializes automatically and exposes window.athos.tracker.
  • npm: run npm install --save @athoscommerce/beacon, then const beacon = new Beacon({ siteId: 'YOUR_SITE_ID' }). Pass { mode: 'development' } as the second argument while testing to keep test events out of reports.
  • On single-page apps, call beacon.pageLoad() on every route change.

2. Collect the IDs

  • chatSessionId: returned by the Init API. Every chat event requires it.
  • responseId: returned by each Send API response. Send it with the events for the products shown in that response.
  • For each product card, record uid (the variant), parentId and sku.

3. Send the Chat Events

EventWhen to sendBeacon.js call
impressionA product card has been at least 70% visible for 1 secondbeacon.events.chat.impression
clickthroughThe shopper clicks a product in the chatbeacon.events.chat.clickThrough
addtocartThe shopper adds a product to the cart from the chatbeacon.events.chat.addToCart
feedbackThe shopper rates the chat session (thumbs up or down)beacon.events.chat.feedback

See Events below for each event's Beacon API endpoint and payload.

beacon.events.chat.impression({ data: {
  chatSessionId: 'chat-session-12345',
  responseId: 'resp-67890',
  results: [{ type: 'product', uid: 'variant-1', parentId: 'product-1', sku: 'SKU-1' }]
}});

4. Count Impressions Correctly

Fire an impression only after a product card has been at least 70% visible for 1 second, and only once per product per response.

Use an IntersectionObserver with threshold: 0.7. Start a 1-second timer when the card becomes visible, and cancel it if the card leaves the viewport first.

See the Impression Tracking Implementation Guide for more detail.

Don't re-send impressions after a reload

"Once per product per response" applies across page loads too. Chat history is typically restored when the shopper navigates to another page or reopens a previous chat session, so the same product cards render again. Impressions that were already sent for them should not be sent a second time.

Keep a record of sent impressions in localStorage, keyed by chatSessionId, then responseId, then product uid, and check it before sending. Remove a session's entries when you drop that chat from your stored history (or once its sessionEndTime has passed) so storage stays bounded.

const IMPRESSIONS_KEY = 'athos-chat-impressions';

function readImpressions() {
  try {
    return JSON.parse(localStorage.getItem(IMPRESSIONS_KEY)) || {};
  } catch {
    return {};
  }
}

function trackChatImpression({ chatSessionId, responseId, product }) {
  const sent = readImpressions();
  if (sent[chatSessionId]?.[responseId]?.[product.uid]) return; // already sent

  beacon.events.chat.impression({ data: {
    chatSessionId,
    responseId,
    results: [{ type: 'product', uid: product.uid, parentId: product.parentId, sku: product.sku }]
  }});

  sent[chatSessionId] ??= {};
  sent[chatSessionId][responseId] ??= {};
  sent[chatSessionId][responseId][product.uid] = true;
  localStorage.setItem(IMPRESSIONS_KEY, JSON.stringify(sent));
}

Implementation Tips

Data Source: All chat event data comes from the Init API and Send API responses.

Send API Tracking Parameters: pageUrl, sessionId and pageLoadId are required on every Send API request, and a request without them is rejected with HTTP 400. Always send userId too, using the Beacon userId. The API accepts requests without it, but Beacon events need it. Add shopperId and currency when available. Use the same values you send in the Beacon context object.

Mapping Product Identifiers: Products in chat responses include uid, parentId and sku. The exception is productRecommendation messages, where each item in recommendationResult[].results[] carries these IDs under mappings.core (mappings.core.uid, mappings.core.parentId, mappings.core.sku). For products without variants, parentId is equal to uid. See the Tracking Overview for detailed examples.


Quick Reference

EventWhenRequired Fields
impressionProducts visiblechatSessionId, responseId, results
clickthroughProduct clickedchatSessionId, responseId, results (1 item)
addtocartProduct added to cartchatSessionId, responseId, results (with qty/price)
feedbackChat session ratedchatSessionId, feedback

Events

1. Impression

Endpoint: POST /{siteId}/chat/impression
When to send: A product card in the chat has been at least 70% visible for 1 second

Required data fields:

  • chatSessionId - Chat session ID from the Init API response
  • responseId - Unique ID from the Send API response that returned the products
  • results - Array of visible products

Product Result object:

{
  "type": "product",
  "parentId": "8128331911111",
  "uid": "8128331907370",
  "sku": "SKU-123"        // optional
}

Example:

{
  "context": { /* see context guide */ },
  "data": {
    "chatSessionId": "2b426e89-c33b-4222-952a-f17db745bc26",
    "responseId": "a907d0ad-720a-4666-b046-00c0c28fb78d",
    "results": [
      {
        "type": "product",
        "parentId": "8128331911111",
        "uid": "8128331907370"
      },
      {
        "type": "product",
        "parentId": "8128331922222",
        "uid": "8128021070122"
      }
    ]
  }
}



2. Clickthrough

Endpoint: POST /{siteId}/chat/clickthrough
When to send: Shopper clicks a product in the chat (navigates to PDP)

Required data fields:

  • chatSessionId - Chat session ID from the Init API response
  • responseId - Unique ID from the Send API response that returned the product
  • results - Single clicked product (exactly 1)
{
  "context": { /* see context guide */ },
  "data": {
    "chatSessionId": "2b426e89-c33b-4222-952a-f17db745bc26",
    "responseId": "a907d0ad-720a-4666-b046-00c0c28fb78d",
    "results": [
      {
        "type": "product",
        "parentId": "8128331911111",
        "uid": "8128331907370"
      }
    ]
  }
}



3. Add to Cart

Endpoint: POST /{siteId}/chat/addtocart
When to send: Shopper adds a product to the cart from the chat

Required data fields:

  • chatSessionId - Chat session ID from the Init API response
  • responseId - Unique ID from the Send API response that returned the product
  • results - Products added to the cart, each with parentId, uid, qty and price (sku optional)
{
  "context": { /* see context guide */ },
  "data": {
    "chatSessionId": "2b426e89-c33b-4222-952a-f17db745bc26",
    "responseId": "a907d0ad-720a-4666-b046-00c0c28fb78d",
    "results": [
      {
        "parentId": "8128331900000",
        "uid": "8128331907370",
        "qty": 1,
        "price": 22
      }
    ]
  }
}



4. Feedback

Endpoint: POST /{siteId}/chat/feedback
When to send: Shopper rates the chat session with a thumbs up or thumbs down

Feedback applies to the chat session as a whole, not to an individual message, so it does not include a responseId. A common pattern is to prompt for feedback once the assistant has sent a few messages.

Required data fields:

  • chatSessionId - Chat session ID from the Init API response
  • feedback - positive or negative
{
  "context": { /* see context guide */ },
  "data": {
    "chatSessionId": "2b426e89-c33b-4222-952a-f17db745bc26",
    "feedback": "positive"
  }
}