Measure interactions with analytics events

Smart Assistant can publish events that describe how your visitors interact with it: when they open the chat, click a suggestion, receive product recommendations, ask for an agent, and so on.

The events are not tied to any particular tool. Smart Assistant publishes them in the visitor’s browser, and your own page decides what to do with them: send them to Google Analytics, to Google Tag Manager, to another analytics tool, or ignore them.

1. Ask us to enable the events

Analytics events are disabled by default. To enable them for your instance, contact the Usizy team. Until we enable them, Smart Assistant publishes nothing, so adding the code below has no effect.

2. Listen to the events

Every event is published as a standard browser CustomEvent named sa:event, and the event itself is in its detail property.

The event bubbles up through the page, so you can listen on document without referencing the assistant:

document.addEventListener('sa:event', (e) => {
    console.log(e.detail.event, e.detail)
})

To keep it simple, you can also listen on the <smart-assistant> element itself:

document.querySelector('smart-assistant').addEventListener('sa:event', (e) => {
    console.log(e.detail)
})

3. What an event looks like

{
  "event": "product_clicked",
  "version": 1,
  "event_id": "01a1caf0-e3de-7146-bf14-4dbe0ca5d8ca",
  "timestamp": "2026-11-11T10:00:00.000Z",
  "source": "widget",
  "instance": "your-instance",
  "conversation_id": null,
  "anonymous_id": "",
  "properties": { "product_id": "12345" }
}
FieldDescription
eventName of the event, in lowercase snake_case. See the list below.
versionVersion of the event format. It is 1 today.
event_idUnique identifier of the event. Use it to discard duplicates in your analytics tool.
timestampWhen the event happened, in ISO 8601 format.
sourcewidget for events that happen on the screen (clicks, opening the chat) and backend for events that happen in the conversation (a recommendation, a handoff to an agent).
instanceIdentifier of your Smart Assistant instance.
conversation_idIdentifier of the conversation. Only present on backend events.
anonymous_idPseudonymous identifier of the visitor, stable within your instance. Only present on backend events. It cannot be traced back to the visitor and is different for every instance.
propertiesExtra details about the event. They are plain values (text, numbers, true/false), never nested objects.

None of the events contains personal data: they never include the visitor’s messages, name, email or any other text the visitor has typed.

4. Events

Events from the screen (source: widget)

EventWhenProperties
chat_openedThe chat window goes from closed to open.None
chat_closedThe chat window is closed.None
suggestion_clickedThe visitor clicks a suggestion or menu button.label: text of the button. subtopic: topic of the button, or null.
product_clickedThe visitor clicks a product in a recommendation carousel.product_id: identifier of the product in your catalogue.

Events from the conversation (source: backend)

EventWhenProperties
conversation_startedA new conversation begins and the assistant greets the visitor.language: language of the conversation, for example en.
product_recommendedThe assistant shows a carousel of products or outfits.kind: products or outfits. count: number of products (or outfits) shown. flow: internal name of the flow that produced it.
flow_startedThe assistant starts a guided process (a size recommendation, an order lookup…).flow: internal name of the process.
flow_completedA guided process finishes.flow: internal name of the process.
handoff_to_agentThe conversation is handed over to a human agent.ticket_system: zendesk, email or native. reason: why the handoff happened, one of request, suggested, critical, angry, unknown or none.
feedback_givenThe visitor rates the conversation or a message.scope: conversation or message. rating: the score given. For message, 1 is thumbs up and 0 is thumbs down. feedback_type: only for conversation, one of Star, CSAT, NPS or Binary.

backend events travel through the live chat connection, so they are published while the chat is connected.

5. Send the events to Google Tag Manager

If you use Google Tag Manager, the simplest option is to let Smart Assistant push its events to the dataLayer. Add the analytics-datalayer attribute to the Smart Assistant element:

<smart-assistant api-key="YOUR_API_KEY" analytics-datalayer></smart-assistant>

Every event is then pushed to window.dataLayer with the name prefixed by sa_, so it never collides with your own events:

{
  event: 'sa_product_clicked',
  product_id: '12345',
  sa_event_id: '01a1caf0-e3de-7146-bf14-4dbe0ca5d8ca',
  sa_instance: 'your-instance',
  sa_conversation_id: null
}

The properties of the event (here product_id) are added to the same object, and the identifying fields get the sa_ prefix. The dataLayer does not include anonymous_id, source or timestamp. If you need them, use the browser event described in section 2.

In Google Tag Manager:

  1. Create a Custom Event trigger whose event name is, for example, sa_product_clicked. Use Some Custom Events with a regular expression such as ^sa_ to catch all of them with one trigger.
  2. Create Data Layer Variables for the properties you want to use, for example product_id.
  3. Create a tag (for instance a Google Analytics: GA4 Event tag) that fires on that trigger and sends the parameters you need.

6. Send the events to Google Analytics without Tag Manager

If you use gtag directly, listen to the browser event and translate it. This example maps the product click to the recommended GA4 event select_item and sends the rest as custom events:

document.addEventListener('sa:event', (e) => {
    const { event, properties } = e.detail

    if (event === 'product_clicked') {
        gtag('event', 'select_item', {
            items: [{ item_id: properties.product_id }]
        })
        return
    }

    gtag('event', `sa_${event}`, properties)
})

Smart Assistant only publishes the events in the visitor’s browser, and it never includes personal data in them. Whether those events are then sent to Google Analytics or to any other tool is decided by your page.

Make sure your listener (or your Google Tag Manager tags) respects your visitors’ choices. For example, only start sending events once the visitor has accepted the analytics category in your cookie banner:

document.addEventListener('sa:event', (e) => {
    if (!window.myConsent?.analytics) {
        return
    }
    // send the event to your analytics tool
})

Here window.myConsent stands for whatever your own consent management platform provides.

See Consent Management for how consent works in Smart Assistant.