Safety events

Conversational agent safety events flag errors and performance issues so you can detect and resolve them fast. For remediation guidance, see Conversational agent optimization.

clarity_error

Tracked when Conversational agent encounters a recoverable error that the system caught and handled. Conversational agent may keep running after the error, but the event signals that something went wrong and needs investigation.

Attributes

Attribute	Description	Values
`action`	Event action type.	`clarity_error`
`type`	The specific error condition.	Common conditions include empty or invalid product IDs, and product IDs that aren't returned as strings.
`location`	Where the error originated	See values
`message`	Error message.	Free-text
`chat_widget_state`	State of the chat widget when the error occurred, when applicable.	`minimized`, `bubble`, `open`
`chat_widget_size`	Size of the chat widget, when applicable.	`large`, `small`, `half_screen`, `full_screen`
`conversation_state`	State of the conversation, when applicable.	`initial_message`, `welcome_message`, `home_screen`, `conversation`, `idle`
`chat_config`	Webchat configuration, when applicable.	JSON string
`latency`	For backend errors, time elapsed before the error, in milliseconds.	Example: `1240`

location values

location value	Description
`FE:chat_close`	The error occurred when the chat window was closed or dismissed.
`FE:user_active`	The error occurred while the shopper was actively using the chat.
`FE:user_passive`	The error occurred while the chat was open, but the shopper wasn't interacting with it.
`Back_end`	The error originated on the server. This is not related to your browser or actions.
`FE:app_error_boundary`	A critical error caused the chat to stop working unexpectedly.

clarity_warning

Tracked when Conversational agent hits a recoverable issue that doesn't stop it from running, but is worth flagging. It carries lower severity than clarity_error.

Attributes

Attribute	Description	Values
`action`	Event action type.	`clarity_warning`
`type`	The specific warning condition.	Common conditions include misconfigurations, unrecognized hook keys, or deprecated configuration values.
`message`	Warning message.	Free-text
`chat_widget_state`	State of the chat widget when the warning occurred.	`minimized`, `bubble`, `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

load_failed

Tracked when a blocking condition prevents Conversational agent from loading or rendering. The shopper won't see Conversational agent from this code path.

Attributes

Attribute	Description	Values
`action`	Event action type.	`load_failed`
`type`	The specific failure condition.	See conditions below
`message`	Error message.	Free-text

type conditions

`type` value	Meaning
`banner_id_not_set`	The use case configuration is missing the banner ID.
`parent_element_not_found`	The CSS selector for the trigger's parent element didn't match anything on the page.
`configuration_error`	The Conversational agent configuration was invalid.
`required_values_not_found`	A product ID, agent ID, or URL was missing during product detail retrieval.
`item_not_found`	A product details fetch returned an empty result.
`product_ids_failed`	Extracting product IDs from the page failed.
`page_type_failed`	Page type detection failed.
`page_api_not_available`	Page API was unavailable.
`healthcheck_failed`	The Conversational agent backend health check failed.
`outside_working_hours`	The current time is outside the use case's configured working hours.
`external_data_failed`	Third-party experiment data couldn't be matched to a known variant.

trigger_error

Tracked when a trigger encounters a non-blocking error while loading. Fires for triggers that make additional requests, such as PDP-embedded triggers with AI-generated conversation starters and search suggestions.

Attributes

Attribute	Description	Values
`action`	Event action type.	`trigger_error`
`component`	Trigger surface type.	`PDP_EMBEDDED`, `SEARCH_SUGGESTION`
`component_template`	Template version.	`PDP_EMBEDDED_v1`, `SEARCH_SUGGESTION_v1`
`trigger_context_product_ids`	Product IDs extracted from the page by the trigger.	Array of product IDs
`location`	The stage of the trigger execution flow where the error occurred.	Same value set as `clarity_error`
`message`	Error message.	Free-text
`chat_config`	Webchat configuration.	JSON string