Skip to main content
Embedded web chat supports a variety of events that allow you to trigger specific actions or customize behavior at different stages of the chat lifecycle. Events enable you to intercept, modify, or respond to user interactions and system state changes in real time. The following tables list all supported events, grouped by category.

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

  1. Use once() for one-time operations
    If you only need to handle an event once, use instance.once() instead of instance.on() to automatically remove the handler after execution.
  2. Clean up event handlers
    Use instance.off() to remove event handlers when they’re no longer needed to prevent memory leaks.
  3. Handle errors gracefully
    Wrap event handler logic in try-catch blocks to prevent errors from breaking the chat experience.
  4. 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.content to change the user’s message before sending.
  • pre:receive Modify event.message.content to change the agent’s response before rendering.
  • pre:stream:delta Modify event.delta.text to transform streaming content in real-time before it’s rendered.
  • pre:threadLoaded Modify event.messages to customize historical messages before display.
  • view:pre:change Modify event.newViewState to control the upcoming view state.

Common use cases

  • Analytics tracking Use send, receive, and view:change events to track user interactions.
  • Custom rendering Use userDefinedResponse to render custom UI for specialized content types.
  • Token management Use authTokenNeeded to implement automatic token refresh.
  • Message transformation Use pre:send and pre:receive to transform messages in transit.
  • Streaming content processing Use pre:stream:delta to filter, transform, or monitor streaming responses in real-time.
  • Feedback collection Use feedback event to capture and process user feedback.