Methods
Public JavaScript methods available on the virbe-plugin element for controlling conversations, audio, and the widget UI.
All methods are called directly on the <virbe-plugin> DOM element. Get a reference to it first:
const widget = document.querySelector('virbe-plugin');Widget Visibility
showWidget()
Makes the widget visible. In floating mode this opens the expanded widget panel.
widget.showWidget();hideWidget()
Hides the widget. In floating mode this collapses the widget back to the avatar bubble.
widget.hideWidget();Conversation Control
startNewConversation(endUserId, variables?)
Starts a fresh conversation.
- endUserId (
string) – Identifier for the end user. - variables (
ConversationMessageVariableStoreDto[], optional) – Context variables to pass to the conversation engine.
widget.startNewConversation('user-123', [
{ key: 'email', value: '[email protected]' },
]);startConversation(conversationId, endUserId?, variables?)
Resumes or loads an existing conversation by ID.
- conversationId (
string) – The conversation to load. - endUserId (
string, optional) – Identifier for the end user. - variables (
ConversationMessageVariableStoreDto[], optional) – Context variables to pass to the conversation engine.
widget.startConversation('conv-abc-123', 'user-123');stopConversation()
Ends the current conversation.
widget.stopConversation();Audio Control
mute()
Mutes the virtual being's audio output.
widget.mute();unmute()
Unmutes the virtual being's audio output.
widget.unmute();startSpeechRecord()
Starts recording the user's speech via the microphone.
widget.startSpeechRecord();stopSpeechRecord()
Stops recording the user's speech.
widget.stopSpeechRecord();interruptSpeech()
Immediately interrupts the virtual being's current speech playback.
widget.interruptSpeech();Messaging
sendSignal(signal, value?)
Sends a named signal to the conversation engine. Signals can trigger specific flows or behaviors configured in the dashboard.
- signal (
string) – The signal name. - value (
string, optional) – An optional value to include with the signal.
widget.sendSignal('conversation-start');
widget.sendSignal('navigate', '/checkout');sendText(text, language?)
Sends a text message to the conversation as if the user had typed it.
- text (
string) – The message text. - language (
string, optional) – Language code (e.g."en","pl").
widget.sendText('Hello, I need help with my order');
widget.sendText('Bonjour', 'fr');storeVariable(key, value)
Stores a key-value pair in the conversation's variable store. Stored variables are accessible by the conversation engine.
- key (
string) – Variable name. - value (
string) – Variable value.
widget.storeVariable('userPlan', 'enterprise');Appearance
updateStyles(colors)
Updates the widget's color scheme at runtime.
- colors (
object)- bg (
string, optional) – Background color. Defaults to#ffffff. - text (
string, optional) – Text color. Defaults to#374151. - accent (
string, optional) – Accent color. Defaults to#1e429f.
- bg (
widget.updateStyles({
bg: '#1a1a2e',
text: '#e0e0e0',
accent: '#e94560',
});Event Subscription
subscribeToEvent(event, listener)
Subscribes to a specific widget event. Returns a subscription object with an unsubscribe() method.
- event (
string) – The event name. See Events for the full list. - listener (
(event: CustomEvent) => void) – Callback function.
Returns { unsubscribe: () => void }.
const subscription = widget.subscribeToEvent('onConversationMessage', (event) => {
console.log('Message received:', event.detail.action);
});
// Later, to stop listening:
subscription.unsubscribe();You can also use standard DOM addEventListener – see the Events page for details on both approaches.
Complete Example
This example shows a typical initialization flow – waiting for the widget to be ready, then starting a conversation:
const widget = document.querySelector('virbe-plugin');
// 1. Wait for the widget to initialize
widget.subscribeToEvent('onInitialized', () => {
console.log('Widget is ready');
});
// 2. React to API connection status
widget.subscribeToEvent('onApiStatusChanged', (event) => {
const status = event.detail.action;
console.log('API status:', status);
if (status === 'connected') {
// 3. Start a new conversation once connected
widget.unmute();
widget.startNewConversation('user-123');
}
});
// 4. Listen for conversation messages
const msgSub = widget.subscribeToEvent('onConversationMessage', (event) => {
const message = event.detail.action;
console.log('Conversation message:', message);
});
// 5. Listen for signal actions from the backend
widget.subscribeToEvent('onSignalAction', (event) => {
const signal = event.detail.action;
console.log('Signal received:', signal);
});