- Conversation events
- Customization events
- Feedback events
- Lifecycle events
- Message events
- Security events
- View events
Conversation events
Conversation events track conversation lifecycle operations such as restarts and thread loading.Customization events
Customization events enable you to handle custom response types and render custom UI elements.Feedback events
Feedback events track user interactions with feedback controls on messages. For a complete guide on implementing thumbs-up and thumbs-down feedback, see Thumbs-up and thumbs-down feedback.Lifecycle events
Lifecycle events track the initialization and readiness state of the chat widget.Message events
Message events allow you to intercept and modify messages as they flow between the user and the agent.Security events
Security events help manage authentication and token lifecycle.View events
View events track changes to the chat widget’s visual state and layout.Complete example
The following example demonstrates how to configure multiple events in the embedded web chat:Best practices
Event handler patterns
-
Use
once()for one-time operations
If you only need to handle an event once, useinstance.once()instead ofinstance.on()to automatically remove the handler after execution. -
Clean up event handlers
Useinstance.off()to remove event handlers when they’re no longer needed to prevent memory leaks. -
Handle errors gracefully
Wrap event handler logic in try-catch blocks to prevent errors from breaking the chat experience. -
Avoid blocking operations
Keep event handlers lightweight and non-blocking. Use async operations for heavy processing.
Modifying event data
-
pre:send
Modify
event.message.message.contentto change the user’s message before sending. -
pre:receive
Modify
event.message.contentto change the agent’s response before rendering. -
pre:stream:delta
Modify
event.delta.textto transform streaming content in real-time before it’s rendered. -
pre:threadLoaded
Modify
event.messagesto customize historical messages before display. -
view:pre:change
Modify
event.newViewStateto control the upcoming view state.
Common use cases
-
Analytics tracking
Use
send,receive, andview:changeevents to track user interactions. -
Custom rendering
Use
userDefinedResponseto render custom UI for specialized content types. -
Token management
Use
authTokenNeededto implement automatic token refresh. -
Message transformation
Use
pre:sendandpre:receiveto transform messages in transit. -
Streaming content processing
Use
pre:stream:deltato filter, transform, or monitor streaming responses in real-time. -
Feedback collection
Use
feedbackevent to capture and process user feedback.

