Events

The <virbe-plugin> element emits custom DOM events that your application can listen to. All events bubble and are composed (they cross shadow DOM boundaries), so you can listen on the element itself or on a parent.

Listening to EventsCopy Anchor Link

There are two ways to subscribe:

subscribeToEvent() (recommended)Copy Anchor Link

Returns a subscription object with a clean unsubscribe() method:

const widget = document.querySelector('virbe-plugin');

const subscription = widget.subscribeToEvent('onConversationMessage', (event) => {
  console.log(event.detail.action);
});

// Stop listening
subscription.unsubscribe();

addEventListener()Copy Anchor Link

Standard DOM event listening. Use removeEventListener() to unsubscribe:

function handleMessage(event) {
  console.log(event.detail.action);
}

widget.addEventListener('onConversationMessage', handleMessage);

// Stop listening
widget.removeEventListener('onConversationMessage', handleMessage);

Lifecycle EventsCopy Anchor Link

onInitializedCopy Anchor Link

Fired when the widget has fully loaded and is ready to accept method calls.

• Payload: none

widget.subscribeToEvent('onInitialized', () => {
  console.log('Widget is ready');
});

onApiStatusChangedCopy Anchor Link

Fired when the connection to the Virbe backend changes state.

• Payload: { action: ApiStatus } – The new connection status (e.g. "connected", "disconnected", "reconnecting").

widget.subscribeToEvent('onApiStatusChanged', (event) => {
  console.log('Connection status:', event.detail.action);
});

onErrorNoticeCopy Anchor Link

Fired when an error occurs within the widget.

• Payload: { error: ErrorNotice } – Error details.

widget.subscribeToEvent('onErrorNotice', (event) => {
  console.error('Widget error:', event.detail.error);
});

Conversation EventsCopy Anchor Link

onConversationMessageCopy Anchor Link

Fired for each message in the conversation (both user and virtual being messages).

• Payload: { action: ConversationMessageDto } – The full message object.

widget.subscribeToEvent('onConversationMessage', (event) => {
  const message = event.detail.action;
  console.log('Message:', message);
});

onSignalActionCopy Anchor Link

Fired when a signal action is received from the conversation engine. Signals are configured in the dashboard to trigger specific behaviors.

• Payload: { action: ConversationMessageSignalDto } – The signal data.

widget.subscribeToEvent('onSignalAction', (event) => {
  const signal = event.detail.action;
  if (signal.name === 'handover') {
    // Trigger human handover flow
  }
});

onCustomMessageActionCopy Anchor Link

Fired when a custom message action is received from the backend.

• Payload: { action: ConversationMessageCustomActionDto } – The custom action data.

onVariableStoreCopy Anchor Link

Fired when a variable is stored or updated in the conversation.

• Payload: { action: ConversationMessageVariableStoreDto } – The variable key-value pair.

widget.subscribeToEvent('onVariableStore', (event) => {
  const { key, value } = event.detail.action;
  console.log(`Variable stored: ${key} = ${value}`);
});

onToolCallCopy Anchor Link

Fired when the conversation engine triggers a tool/function call.

• Payload: { action: ConversationMessageToolCallDto } – The tool call details.

widget.subscribeToEvent('onToolCall', (event) => {
  const toolCall = event.detail.action;
  console.log('Tool called:', toolCall);
});

onFlowActionCopy Anchor Link

Fired when a flow transition occurs in the conversation engine.

• Payload: { action: ConversationFlowActionDto } – The flow action data.

Speech EventsCopy Anchor Link

onStartedSpeakingCopy Anchor Link

Fired when the virtual being starts speaking.

• Payload: none

widget.subscribeToEvent('onStartedSpeaking', () => {
  console.log('Being is speaking...');
});

onEndedSpeakingCopy Anchor Link

Fired when the virtual being finishes speaking.

• Payload: none

widget.subscribeToEvent('onEndedSpeaking', () => {
  console.log('Being finished speaking');
});

onInterruptSpeechClickedCopy Anchor Link

Fired when the user clicks the interrupt button to stop the virtual being's speech.

• Payload: none

UI and Behavior EventsCopy Anchor Link

onUiActionCopy Anchor Link

Fired when a UI action is requested by the conversation engine – for example, displaying buttons or cards for the user to interact with.

• Payload: { action: ConversationMessageUiActionDto } – Contains arrays of cards and buttons.

widget.subscribeToEvent('onUiAction', (event) => {
  const { cards, buttons } = event.detail.action;
  console.log('UI elements:', { cards, buttons });
});

onBehaviourActionCopy Anchor Link

Fired when a behavior action is triggered by the conversation engine.

• Payload: { action: ConversationMessageBehaviourActionDto } – The behavior action data.

onEngineEventCopy Anchor Link

Fired for low-level engine events from the backend.

• Payload: { event: ConversationMessageEngineEventDto } – The engine event data.

Event Reference TableCopy Anchor Link

Cleanup PatternCopy Anchor Link

When subscribing to multiple events, store subscriptions and unsubscribe when no longer needed:

const subscriptions = [];

subscriptions.push(
  widget.subscribeToEvent('onInitialized', () => { /* ... */ })
);
subscriptions.push(
  widget.subscribeToEvent('onConversationMessage', (e) => { /* ... */ })
);
subscriptions.push(
  widget.subscribeToEvent('onApiStatusChanged', (e) => { /* ... */ })
);

// Unsubscribe all at once
function cleanup() {
  subscriptions.forEach((sub) => sub.unsubscribe());
}

Cookie settings