Widget Installation

The OmniBots widget can be installed via a script tag on any website. It works with any frontend framework (React, Vue, Angular, etc.) through the global window.omnibot API. For restricted environments, an iframe embed is also available.

Script Tag (Recommended)

Add the following snippet before the closing </body> tag on every page where you want the widget to appear:

<!-- Load widget CSS and JS -->
<link rel="stylesheet" href="https://omnibots-widget.web.app/widget.css">
<script src="https://omnibots-widget.web.app/widget.iife.js"></script>
<script>
  window.omnibot.init({
    deploymentKey: 'your-deployment-key'
  });
</script>

The widget assets load asynchronously and initialize once the page is ready.

imageWebsite with the OmniBots widget launcher button visible in the bottom-right corner after script tag installation, with chat window closed

Widget appearing on a website after installation

Init Options

Pass these options to window.omnibot.init() to configure the widget:

Option	Type	Required	Default	Description
deploymentKey	string	Yes	—	The deployment key from the OmniBots dashboard (Deploying > Publishing)
position	string	No	'bottom-right'	Launcher position: 'bottom-right' or 'bottom-left'
autoOpen	boolean	No	false	Open the chat window automatically on page load
offset	object	No	{ x: 20, y: 20 }	Pixel offset from the edge of the screen. Set x for horizontal and y for vertical offset
zIndex	number	No	9999	CSS z-index for the widget container. Increase if the widget renders behind other elements on your page
metadata	object	No	{}	Initial page context passed to the bot flow as variables. See Page Context

Example with all options

<link rel="stylesheet" href="https://omnibots-widget.web.app/widget.css">
<script src="https://omnibots-widget.web.app/widget.iife.js"></script>
<script>
  window.omnibot.init({
    deploymentKey: 'your-deployment-key',
    position: 'bottom-right',
    autoOpen: false,
    offset: { x: 20, y: 20 },
    zIndex: 9999,
    metadata: {
      page_label: 'pricing',
      page_url: window.location.href,
      page_title: document.title
    }
  });
</script>

TIP

The metadata option is the key to building page-aware bots. Whatever you pass in metadata is available as flow variables in the bot's Condition and KB Search nodes.

Page Context

Page context lets your bot change behavior based on what page the user is on, who the user is, or any other dynamic information from your website. Context data is passed to the backend and merged into the bot flow's session variables.

Setting Context at Initialization

Use the metadata init option to pass context when the widget loads:

window.omnibot.init({
  deploymentKey: 'your-deployment-key',
  metadata: {
    page_label: 'billing',
    page_url: window.location.href,
    page_title: document.title,
    user_id: 'user_12345',
    user_tier: 'enterprise'
  }
});

Updating Context at Runtime

For single-page apps (SPAs) or when context changes after initialization, use the setContext() method:

// Update context on SPA route change
function onRouteChange(route) {
  window.omnibot.setContext({
    page_label: route.name,
    page_url: window.location.href,
    page_title: document.title
  });
}

// Pass user info after login
function onUserLogin(user) {
  window.omnibot.setContext({
    user_id: user.id,
    user_tier: user.subscription,
    user_name: user.name
  });
}

setContext() merges new fields into the existing context and sends the update to the backend over WebSocket in real time.

Reading Context

Retrieve the current context object at any time:

const ctx = window.omnibot.getContext();
console.log(ctx.page_label); // 'billing'

Context Fields

You can pass any key-value pairs in the context object. The following fields have special meaning:

Field	Description
page_label	Identifies the current page. Used by the KB Search node for dynamic KB lookup and by Condition nodes for page-based routing
page_url	Current page URL — useful for analytics and debugging
page_title	Current page title
user_id	Logged-in user ID — enables personalized experiences
user_tier	Subscription tier — route high-value users differently

Any additional fields you include are available in the flow as {{field_name}}.

Use Case: Page-Based KB Routing

A common pattern is routing to different Knowledge Bases depending on the page. For example, your billing page uses a Billing KB while your product page uses a Product KB.

1. Set page_label in the widget:

   window.omnibot.init({
     deploymentKey: 'your-deployment-key',
     metadata: { page_label: 'billing' }
   });

2. In your flow, use the KB Search node with Dynamic KB enabled. The node reads page_label from the session, finds a Knowledge Base whose name matches "billing", and searches that KB.

   Alternatively, add a Condition node before the KB Search node to explicitly route by page_label:

   Start → Condition (page_label) → KB Search (Billing KB)
                                   → KB Search (Support KB)
                                   → KB Search (General KB)

See the KB Search node documentation for more details on dynamic KB lookup.

JavaScript API

After initialization, the window.omnibot object exposes methods for programmatic control of the widget.

Methods

Method	Description
init(config)	Initialize the widget with the given init options. Can only be called once
open()	Open the chat window
close()	Close the chat window
toggle()	Toggle the chat window open or closed
sendMessage(text)	Send a message to the bot programmatically
toggleFullscreen()	Toggle the widget between normal and fullscreen mode
endSession()	End the current conversation session
setContext(context)	Update page context. Merges with existing context
getContext()	Returns the current page context object, or null if no context is set
on(event, callback)	Subscribe to a widget event
off(event, callback)	Unsubscribe from a widget event
destroy()	Unmount and remove the widget from the page

Events

Listen for widget lifecycle and conversation events:

// Widget is ready
window.omnibot.on('ready', () => {
  console.log('Widget loaded');
});

// User sent a message
window.omnibot.on('message:sent', (data) => {
  console.log('User said:', data.message);
});

// Bot responded
window.omnibot.on('message:received', (data) => {
  console.log('Bot said:', data.content);
});

// Widget opened
window.omnibot.on('open', () => {
  console.log('Chat window opened');
});

// Widget closed
window.omnibot.on('close', () => {
  console.log('Chat window closed');
});

// Conversation escalated to live agent
window.omnibot.on('escalation', (data) => {
  console.log('Escalated to:', data.agent_name);
});

// Session ended
window.omnibot.on('session:end', () => {
  console.log('Session ended');
});

Programmatic Interaction Example

Trigger the bot from a custom button on your page:

<button onclick="window.omnibot.open()">Chat with us</button>
<button onclick="window.omnibot.sendMessage('I need help with billing')">
  Billing Help
</button>

Framework Integration (React, Vue, etc.)

The widget is framework-agnostic and works with any frontend framework. Use the script tag method and interact with the window.omnibot API from your components:

React Example

import { useEffect } from 'react'

function App() {
  useEffect(() => {
    window.omnibot.init({
      deploymentKey: 'your-deployment-key',
      metadata: { page_label: 'dashboard' }
    });
    return () => window.omnibot.destroy();
  }, []);

  return <button onClick={() => window.omnibot.open()}>Chat</button>
}

Vue Example

<script setup>
import { onMounted, onUnmounted } from 'vue'

onMounted(() => {
  window.omnibot.init({
    deploymentKey: 'your-deployment-key',
    metadata: { page_label: 'dashboard' }
  })
})

onUnmounted(() => {
  window.omnibot.destroy()
})
</script>

<template>
  <button @click="window.omnibot.open()">Chat</button>
</template>

TIP

The widget script (widget.iife.js) must be loaded on the page before calling window.omnibot.init(). In SPA frameworks, include the script tag in your index.html or load it dynamically in your app's entry point.

Iframe Embed

For environments where script injection is restricted, you can generate an iframe embed from the deployment settings. Navigate to your bot's Deploying > Publishing page and copy the iframe snippet.

WARNING

The iframe method does not support the JavaScript API for programmatic control. Use the script tag method if you need event hooks, page context, or setContext().

TIP

Add allow="microphone" to the iframe if your bot supports voice input from the widget.