Conversational Assistant Tracking Overview
Beta ReleaseThese 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 exposeswindow.athos.tracker. - npm: run
npm install --save @athoscommerce/beacon, thenconst 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),parentIdandsku.
3. Send the Chat Events
| Event | When to send | Beacon.js call |
|---|---|---|
impression | A product card has been at least 70% visible for 1 second | beacon.events.chat.impression |
clickthrough | The shopper clicks a product in the chat | beacon.events.chat.clickThrough |
addtocart | The shopper adds a product to the cart from the chat | beacon.events.chat.addToCart |
feedback | The 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
| Event | When | Required Fields |
|---|---|---|
| impression | Products visible | chatSessionId, responseId, results |
| clickthrough | Product clicked | chatSessionId, responseId, results (1 item) |
| addtocart | Product added to cart | chatSessionId, responseId, results (with qty/price) |
| feedback | Chat session rated | chatSessionId, 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 responseresponseId- Unique ID from the Send API response that returned the productsresults- 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 responseresponseId- Unique ID from the Send API response that returned the productresults- 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 responseresponseId- Unique ID from the Send API response that returned the productresults- Products added to the cart, each withparentId,uid,qtyandprice(skuoptional)
{
"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 responsefeedback-positiveornegative
{
"context": { /* see context guide */ },
"data": {
"chatSessionId": "2b426e89-c33b-4222-952a-f17db745bc26",
"feedback": "positive"
}
}