Interaction events
Interaction events are driven by the shopper's actions within the chat widget. Each event also carries the default event attributes.
Widget events
Track interactions with the trigger element before a chat session begins.
trigger_clicked
Tracked when the shopper clicks a trigger (a floating button, embedded chip strip, banner, or search suggestion).
Attributes
| Attribute | Description | Values |
action
|
Event action type. | trigger_clicked
|
component
|
Trigger surface type that the shopper clicked to start or continue an interaction. | PDP_EMBEDDED, PLP_EMBEDDED, PLP_BANNER, SEARCH_SUGGESTION, FLOATING_TRIGGER
|
component_template
|
Template version. | PDP_EMBEDDED_v1, PLP_EMBEDDED_v1, PLP_BANNER_v1, SEARCH_SUGGESTION_v1, FLOATING_TRIGGER_v1
|
trigger_context_product_ids
|
Product IDs extracted from the page by the trigger. | Array of product IDs |
trigger_conversation_starters_list
|
Conversation starter texts shown in the trigger. | Array of strings |
trigger_conversation_starter_clicked_is_generated
|
Whether the clicked conversation starter was AI-generated. | true, false
|
trigger_conversation_starters_is_generated
|
Whether the conversation starter set is AI-generated. Logged for PDP-embedded components. | true, false
|
suggested_question_text
|
The conversation starter text that was clicked. | Example: What materials is this product made from?
|
chat_widget_state
|
State of the chat widget at click time. | minimized, bubble, open, none
|
chat_widget_size
|
Size of the chat widget when state=open.
|
large, small, half_screen, full_screen
|
conversation_state
|
State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle, none
|
chat_config
|
Webchat configuration. | JSON string |
Chat lifecycle
The events below describe the chat widget opening, closing, or resizing. Each one identifies how the state change happened.
chat_closed
A catch-all event for chat closures that didn't match any of the specific paths. For example, programmatic closures and edge cases. Low volume in normal usage.
Attributes
| Attribute | Description | Values |
action | Event action type. | chat_closed |
chat_widget_state | State before closing. | minimized, bubble, open |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle |
chat_config | Webchat configuration. | JSON string |
close_chat_from_minimized
Tracked when the shopper dismisses the minimized chat badge entirely.
Attributes
| Attribute | Description | Values |
action | Event action type. | close_chat_from_minimized |
chat_widget_state | State before closing. | minimized |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle |
chat_config | Webchat configuration. | JSON string |
close_chat_from_open_on_mobile
Tracked when a shopper on mobile closes the chat directly from the open state. Mobile only.
Attributes
| Attribute | Description | Values |
action | Event action type. | close_chat_from_open_on_mobile |
chat_widget_state | State before closing. | open |
chat_widget_size | Size of the chat widget. | half_screen, full_screen |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle |
chat_config | Webchat configuration. | JSON string |
expand_from_bubble
Tracked when the shopper opens the chat by clicking the initial message bubble.
Attributes
| Attribute | Description | Values |
action | Event action type. | expand_from_bubble |
chat_widget_state | State of the chat widget. | open |
chat_widget_size | Size of the chat widget. | large, small, half_screen, full_screen |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle |
chat_config | Webchat configuration. | JSON string |
expand_from_minimized
Tracked when the shopper opens the chat from the minimized badge state.
Attributes
| Attribute | Description | Values |
action | Event action type. | expand_from_minimized |
chat_widget_state | State of the chat widget. | open |
chat_widget_size | Size of the chat widget. | large, small, half_screen, full_screen |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle |
chat_config | Webchat configuration. | JSON string |
expand_from_trigger
Tracked when the chat opens because the shopper clicked a trigger.
Attributes
| Attribute | Description | Values |
action | Event action type. | expand_from_trigger |
chat_opened_from_trigger | Banner name of the trigger that opened the chat. | Example: Clarity-PLP-Embedded |
suggested_button | The trigger button (conversation starter) that was clicked. | Example: What materials is this product made from? |
chat_widget_state | State of the chat widget after opening. | open |
chat_widget_size | Size of the chat widget. | large, small, half_screen, full_screen |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle, none |
chat_config | Webchat configuration. | JSON string |
minimize_from_open
Tracked when the shopper minimizes an open chat back to the badge.
Attributes
| Attribute | Description | Values |
action | Event action type. | minimize_from_open |
chat_widget_state | State after minimizing. | minimized |
chat_widget_size | Size of the chat widget before minimizing. | large, small, half_screen, full_screen |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle |
chat_config | Webchat configuration. | JSON string |
Other chat widget controls
change_size
Tracked when the shopper resizes the chat widget.
Attributes
| Attribute | Description | Values |
action | Event action type. | change_size |
set_size_to | New size. | large, small |
chat_widget_size | Size before the resize. | large, small, half_screen, full_screen |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle |
chat_config | Webchat configuration. | JSON string |
close_bubble
Tracked when the shopper dismisses the initial message bubble without opening the chat.
Attributes
| Attribute | Description | Values |
action | Event action type. | close_bubble |
chat_widget_state | State before closing. | bubble |
chat_config | Webchat configuration. | JSON string |
menu_click
Tracked when the shopper clicks an item in the chat header menu. For example, Clear Chat, Learn more, or custom merchant items.
Attributes
| Attribute | Description | Values |
action | Event action type. | menu_click |
button_content | Label of the clicked menu item. | Clear Chat, Learn more, or custom merchant text |
url | URL the menu item leads to, if any. | Example: https://www.example.com/help |
chat_widget_size | Size of the chat widget. | large, small, half_screen, full_screen |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle |
chat_config | Webchat configuration. | JSON string |
Shopper messages
user_respond
Tracked when the shopper sends a text message or interacts in any way that produces a chat input.
Attributes
| Attribute | Description | Values |
action | Event action type. | user_respond |
type | How the input was produced. | text, suggestion_button, quick_reply, trigger_button, voice, product_menu |
message | The text of the message (or the button text, when type is a button). | Message text |
target | Action triggered by the button. Logged only when type is a button and the button has a target. | Example: find_similar_or_compatible_products |
product_ids | Product IDs the shopper had selected when sending the message. | Array of product IDs |
clicked_in_trigger | Banner name of the trigger that initiated this message, when applicable. | Example: Clarity-PDP-Embedded |
chat_widget_size | Size of the chat widget. | large, small, half_screen, full_screen |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle |
chat_config | Webchat configuration. | JSON string |
user_respond_product
Tracked when the shopper asks a question about a specific product. A variant of user_respond with a single-product context.
Attributes
| Attribute | Description | Values |
action | Event action type. | user_respond_product |
type | How the input was produced. | text, suggestion_button, quick_reply, trigger_button, voice, product_menu |
message | Text of the message or button. | Message text |
target | Action triggered by the button. Logged only when type is a button and the button has a target. | Example: find_similar_or_compatible_products |
product_id | The product the question was asked about. | Example: 431374 |
product_category | Category of the product. | Example: outerwear |
clicked_in_trigger | Banner name of the trigger that initiated this message. | Example: Clarity-PDP-Embedded |
chat_widget_size | Size of the chat widget. | large, small, half_screen, full_screen |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle |
chat_config | Webchat configuration. | JSON string |
In-chat clicks
close_mini_pdp
Tracked when the shopper closes the in-chat mini-PDP.
Attributes
| Attribute | Description | Values |
action | Event action type. | close_mini_pdp |
product_id | Product the mini-PDP was showing. | Example: 431374 |
chat_widget_size | Size of the chat widget. | large, small, half_screen, full_screen |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle |
chat_config | Webchat configuration. | JSON string |
mini_pdp_click
Tracked when the shopper opens the in-chat mini-PDP for a product.
Attributes
| Attribute | Description | Values |
action | Event action type. | mini_pdp_click |
product_id | Product opened in the mini-PDP. | Example: 431374 |
product_category | Category of the product. | Example: outerwear |
chat_widget_size | Size of the chat widget. | large, small, half_screen, full_screen |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle |
chat_config | Webchat configuration. | JSON string |
product_menu_click
Tracked when the customer clicks a button in a product item menu.
Attributes
| Attribute | Description | Values |
action | Event action type. | product_menu_click |
button_content | Label of the clicked menu item. | ask follow up, find similar, go to product page |
source_type | Specific layout source of the clicked item menu. | product_card, carousel, mini_pdp |
product_id | Product ID associated with the menu. | Example: 431374 |
product_category | Category of the product. | Example: outerwear |
chat_widget_size | Size of the chat widget. | large, small, half_screen, full_screen |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle |
chat_config | Webchat configuration. | JSON string |
url_click
Tracked when the shopper clicks a URL inside the chat (a product card, a text link, or a mini-PDP product link).
Attributes
| Attribute | Description | Values |
action | Event action type. | url_click |
link_type | Where in the chat the click happened. | product_card, text_url, mini_pdp_product, product_menu |
url | The URL clicked. | Example: https://www.example.com/products/61215 |
product_id | Product ID associated with the link, when link_type is product_card or mini_pdp_product. | Example: 531284 |
product_category | Category of the product. | Example: outerwear |
link_text | Visible text of the link, when link_type is text_url. | Example: Regular Fit Funnel Neck Puffer Jacket |
chat_widget_size | Size of the chat widget. | large, small, half_screen, full_screen |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle |
chat_config | Webchat configuration. | JSON string |
Product selection
product_deselect
Tracked when the shopper deselects a previously selected product.
Attributes
| Attribute | Description | Values |
action | Event action type. | product_deselect |
product_id | The product just deselected. | Example: 431374 |
product_ids | All currently selected products after this deselection. | Array of product IDs |
suggestion_buttons_shown | Suggested buttons shown as a result of this deselection. | Array of button strings |
chat_widget_size | Size of the chat widget. | large, small, half_screen, full_screen |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle |
chat_config | Webchat configuration. | JSON string |
product_select
Tracked when a shopper chooses an item from a list or carousel generated by Clarity during product discovery, indicating their interest in learning more about that specific product.
Attributes
| Attribute | Description | Values |
action | Event action type. | product_select |
product_id | The product the shopper selected. | Example: 431374 |
product_ids | All currently selected products after this selection. | Array of product IDs |
suggestion_buttons_shown | Suggested buttons shown as a result of this selection. | Array of button strings |
chat_widget_size | Size of the chat widget. | large, small, half_screen, full_screen |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle |
chat_config | Webchat configuration. | JSON string |
Feedback
Feedback events record ratings (thumbs up and down) and survey responses. Use these events to track customer satisfaction, identify pain points, and refine messaging.
close_survey
Tracked when the shopper dismisses the survey without submitting.
submit_feedback
Tracked when the shopper submits a survey response.
Attributes
| Attribute | Description | Values |
action | Event action type. | submit_feedback |
feedback_state | Rating given by the shopper. | 1, 2, 3, 4, 5 |
feedback_message | Free-text feedback from the shopper. | Message text |
thumbs_down
Tracked when the shopper gives a negative rating to a Clarity message.
Attributes
| Attribute | Description | Values |
action | Event action type. | thumbs_down |
feedback_message | Optional free-text feedback. | Message text |
feedback_target_text | The Clarity message that was rated. | Message text |
feedback_target_product_ids | Products the shopper was reacting to. | Array of product IDs |
chat_widget_size | Size of the chat widget. | large, small, half_screen, full_screen |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle |
chat_config | Webchat configuration. | JSON string |
thumbs_up
Tracked when the shopper gives a positive rating to a Clarity message.
Attributes
| Attribute | Description | Values |
action | Event action type. | thumbs_up |
feedback_message | Optional free-text feedback. | Message text |
feedback_target_text | The Clarity message that was rated. | Message text |
feedback_target_product_ids | Products the shopper was reacting to. | Array of product IDs |
chat_widget_size | Size of the chat widget. | large, small, half_screen, full_screen |
conversation_state | State of the conversation. | initial_message, welcome_message, home_screen, conversation, idle |
chat_config | Webchat configuration. | JSON string |