Embedding & JavaScript API

The OmniBots widget is loaded with a single script tag and initialized through the omnibot global object. This page covers the full JavaScript API, configuration options, theme system, launcher styling, and info message (teaser bubble) configuration.

Quick Start

Add the widget script to your page and call omnibot.init() with your deployment key:

<!-- Load the widget -->
<script src="https://omnibots-widget.web.app/widget.iife.js" defer></script>

<script>
  // Wait for the script to load, then initialize
  window.addEventListener('load', () => {
    omnibot.init({
      deploymentKey: 'your-deployment-key',
      position: 'bottom-right',
      offset: { x: 20, y: 20 },
      zIndex: 9999,
      autoOpen: false,
      metadata: {
        page_label: 'pricing',
        user_tier: 'enterprise'
      }
    });
  });
</script>

imageWebsite with the initialized OmniBots widget showing the launcher button in the bottom-right corner and the chat window open with a welcome message

Widget after initialization on a website

Async Loading

The widget supports queued commands for async script loading. Commands pushed to window.omnibotQueue before the script loads will be processed automatically once the widget initializes.

WidgetConfig

The omnibot.init() method accepts a WidgetConfig object:

Property	Type	Default	Description
deploymentKey	string	(required)	Unique key identifying the bot deployment
position	'bottom-right' | 'bottom-left'	'bottom-right'	Corner of the screen for the widget
offset	{ x: number, y: number }	{ x: 20, y: 20 }	Pixel offset from the corner
zIndex	number	9999	CSS z-index for the widget container
autoOpen	boolean	false	Automatically open the chat window on load
metadata	Record<string, unknown>	undefined	Initial page context metadata (see PageContext)

JavaScript API Methods

The omnibot global object exposes the following methods:

Widget Lifecycle

Method	Description
init(config)	Initialize the widget with the given configuration. Logs a warning if called more than once.
destroy()	Unmount the widget, remove its DOM container, and clear all event listeners.

Window Control

Method	Description
open()	Open the chat window.
close()	Close the chat window.
toggle()	Toggle the chat window open or closed.
toggleFullscreen()	Toggle between normal and fullscreen mode.

Messaging

Method	Description
sendMessage(msg)	Send a text message on behalf of the user. The message appears in the chat and is sent to the backend.
endSession()	End the current conversation session. Clears messages and starts fresh.

Page Context

Method	Description
setContext(ctx)	Update the page context. Merged with existing context and sent to the backend for flow routing decisions.
getContext()	Return the current PageContext object, or null if no context is set.

Event Handling

Method	Description
on(event, callback)	Subscribe to a widget event.
off(event, callback)	Unsubscribe from a widget event.

Events

Subscribe to events using omnibot.on(event, callback):

Widget Lifecycle

Event	Payload	Description
ready	none	Widget has been initialized and is ready
open	none	Chat window opened
close	none	Chat window closed
fullscreen	none	Entered fullscreen mode
fullscreen:exit	none	Exited fullscreen mode
connected	none	WebSocket connected to the backend
disconnected	none	WebSocket disconnected
error	{ message }	An error occurred

Messaging

Event	Payload	Description
message:sent	{ message, attachments? }	User sent a message. message is the text string, attachments is an optional array of file attachments
message:received	ChatMessage	Bot or agent message received
conversation:started	none	A new conversation session began
session:end	none	Conversation session ended

Escalation & Agents

Event	Payload	Description
escalation	EscalationMessage	Conversation escalated to live agent
escalation:ended	none	Live agent escalation ended
escalation:failed	{ reason }	Escalation attempt failed
agent:joined	{ agent_name }	A live agent joined the conversation
agent:message	ChatMessage	Live agent sent a message
queue:update	{ position, estimated_wait }	Queue position update during escalation

Audio & Video

Event	Payload	Description
audio:config	AudioConfigMessage	Audio configuration received from backend
audio:received	audio data	Audio response received (for TTS)
audio:transcription	{ text }	Speech-to-text transcription received
tts:playing	none	Text-to-speech audio started playing
video:invite	{ session_id, room_id }	Agent initiated a video call
video:ended	none	Video call ended

Other

Event	Payload	Description
prechat:submit	VisitorInfo	Pre-chat form submitted
feedback:submitted	{ message_id, rating }	User submitted message feedback
context:updated	PageContext	Page context was updated
hub:config	hub config	Hub/department configuration received
hub:agent_switch	{ agent }	Switched to a different agent in hub mode
custom:event	{ event_name }	Custom event from popup menu item

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

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

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

PageContext

Page context allows you to pass information about the current page to the bot's flow engine. The flow can use context fields (such as page_label) to route conversations to different branches.

interface PageContext {
  page_label?: string;    // Label for current page (e.g., "billing", "support")
  page_url?: string;      // Current page URL
  page_title?: string;    // Current page title
  user_id?: string;       // Logged-in user ID
  user_tier?: string;     // User subscription/tier level
  [key: string]: unknown; // Any additional custom fields
}

Context can be set at initialization via metadata or updated at any time:

// Set at init
omnibot.init({
  deploymentKey: 'abc123',
  metadata: { page_label: 'checkout', user_tier: 'pro' }
});

// Update later (e.g., on SPA route change)
omnibot.setContext({ page_label: 'account-settings' });

Context Merging

Calling setContext() merges the new fields with the existing context. To clear a field, explicitly set it to null.

Theme System

The widget's visual appearance is controlled by the WidgetTheme object, which is configured per-bot in the Operations Portal and delivered to the widget at runtime via WebSocket. The theme maps to over 40 CSS custom properties using the --ob- prefix.

imageAnnotated widget diagram with arrows mapping theme color properties to UI parts: primary_color to header, user_bubble_color to user messages, bot_bubble_color to bot messages, button colors to action buttons

Theme properties mapped to widget UI elements

Core Theme Properties

Property	Type	Default	Description
primary_color	string	'#6366F1'	Primary brand color used for header, buttons, and accents
header_background	string	(uses primary_color)	Header background color
header_text_color	string	'#FFFFFF'	Header text color
user_bubble_color	string	(uses primary_color)	Background color of user message bubbles
user_text_color	string	'#FFFFFF'	Text color inside user bubbles
bot_bubble_color	string	'#FFFFFF'	Background color of bot message bubbles
bot_text_color	string	'#1F2937'	Text color inside bot bubbles
system_bubble_color	string	'#E5E7EB'	Background color of system messages
system_text_color	string	'#6B7280'	Text color of system messages

Font Properties

Property	Type	Default	Description
font_family	string	System font stack	Font family for the widget
font_size	string	'14px'	Base font size
font_weight	string	'400'	Base font weight
header_font_size	string	'16px'	Header title font size

Bubble Styling

Property	Type	Default	Description
bubble_border_radius	string	'16px'	Border radius for message bubbles
bot_bubble_border_color	string	transparent	Border color for bot bubbles
bot_bubble_border_width	string	'0'	Border width for bot bubbles
user_bubble_border_color	string	transparent	Border color for user bubbles
user_bubble_border_width	string	'0'	Border width for user bubbles

Background Colors

Property	Type	Description
widget_background_color	string	Overall widget background
message_area_background_color	string	Message list area background

Button Styling

These properties control quick reply buttons, action buttons, and link buttons:

Property	Type	Description
button_background_color	string	Background color of action buttons
button_text_color	string	Text color of action buttons
button_border_color	string	Border color of action buttons
button_border_radius	string	Border radius of action buttons
button_hover_background_color	string	Hover background for action buttons
button_font_size	string	Button font size
button_font_family	string	Button font family
button_font_weight	string	Button font weight
button_padding	string	Button padding (default: '8px 14px')
button_text_align	string	Text alignment within buttons (default: 'center')
button_margin_top	string	Top margin for button container
button_margin_bottom	string	Bottom margin for button container
button_margin_left	string	Left margin for button container
button_margin_right	string	Right margin for button container
link_button_background_color	string	Background for URL buttons
link_button_text_color	string	Text color for URL buttons
link_button_border_color	string	Border color for URL buttons
link_button_border_radius	string	Border radius for URL buttons

Toolbar

Property	Type	Description
toolbar_height	string	Custom height for the widget toolbar/header area

Feedback Button Styling

Property	Type	Description
feedback_submit_background_color	string	Submit button background in feedback form
feedback_submit_text_color	string	Submit button text color
feedback_submit_border_radius	string	Submit button border radius
feedback_close_background_color	string	Close button background in feedback form
feedback_close_text_color	string	Close button text color
feedback_close_border_radius	string	Close button border radius

Widget Size

The widget window dimensions are configurable:

Property	Type	Default	Description
width	number	380	Widget width in pixels
height	number	600	Widget height in pixels
max_height_percent	number	90	Maximum height as a percentage of the viewport

interface WidgetSizeConfig {
  width?: number;            // Default: 380px
  height?: number;           // Default: 600px
  max_height_percent?: number; // Default: 90% of viewport
}

Launcher Style

The floating launcher button can be customized:

Property	Type	Default	Description
size	number	60	Launcher button diameter in pixels
icon_type	'default' | 'custom' | 'text'	'default'	Icon style for the launcher
custom_icon_url	string	undefined	URL to a custom image icon (when icon_type is 'custom')
text_icon	string	undefined	Text or emoji displayed as the icon (when icon_type is 'text')
edge	'left' | 'right'	'right'	Which side of the screen the launcher appears on
offset_x	number	20	Horizontal offset from the edge in pixels
offset_y	number	20	Vertical offset from the bottom in pixels
border_radius	number	30	Border radius in pixels (half of size = circle)
shadow	boolean	true	Whether to show a drop shadow

interface LauncherStyleConfig {
  size?: number;
  icon_type?: 'default' | 'custom' | 'text';
  custom_icon_url?: string;
  text_icon?: string;
  edge?: 'left' | 'right';
  offset_x?: number;
  offset_y?: number;
  border_radius?: number;
  shadow?: boolean;
}

Info Message (Teaser Bubble)

The info message is a teaser bubble that appears above the launcher button to proactively engage visitors. It can display a message and optional action buttons.

Property	Type	Default	Description
enabled	boolean	false	Whether the info message is enabled
message	string		Text content of the teaser bubble
delay_seconds	number	3	Delay before showing the bubble
show_once_per_session	boolean	true	Only show once per browser session
background_color	string		Bubble background color
text_color	string		Bubble text color
border_radius	string		Bubble border radius
max_width	string		Maximum width of the bubble
show_close_button	boolean		Whether to show a close (X) button
buttons	InfoMessageButton[]	[]	Action buttons inside the bubble
button_background_color	string		Button background color
button_text_color	string		Button text color
button_border_radius	string		Button border radius

Info Message Buttons

Each button in the info message supports three action types:

Action	Description
open_chat	Opens the chat window
url	Opens a URL in a new tab
postback	Sends a payload to the bot as if the user typed it

interface InfoMessageButton {
  label: string;
  action: 'open_chat' | 'url' | 'postback';
  url?: string;      // For 'url' action
  payload?: string;   // For 'postback' action
}

Full Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>My Website</title>
</head>
<body>
  <h1>Welcome to our site</h1>

  <!-- Load the OmniBots widget -->
  <script src="https://omnibots-widget.web.app/widget.iife.js" defer></script>

  <script>
    window.addEventListener('load', () => {
      // Initialize the widget
      omnibot.init({
        deploymentKey: 'deploy_abc123xyz',
        position: 'bottom-right',
        offset: { x: 24, y: 24 },
        zIndex: 10000,
        autoOpen: false,
        metadata: {
          page_label: 'homepage',
          page_url: window.location.href,
          page_title: document.title,
          user_id: 'usr_12345',
          user_tier: 'premium'
        }
      });

      // Listen for events
      omnibot.on('ready', () => {
        console.log('OmniBots widget is ready');
      });

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

      omnibot.on('message:received', (msg) => {
        console.log('Received:', msg.content);
      });

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

      // Example: Open chat from a custom button
      document.getElementById('help-btn')?.addEventListener('click', () => {
        omnibot.open();
        omnibot.sendMessage('I need help with my order');
      });

      // Example: Update context on SPA navigation
      window.addEventListener('popstate', () => {
        omnibot.setContext({
          page_url: window.location.href,
          page_title: document.title
        });
      });
    });
  </script>

  <button id="help-btn">Need Help?</button>
</body>
</html>

Deployment Key

Never expose a deployment key for a bot that has access to sensitive internal systems. Deployment keys are public-facing and should be scoped to visitor-facing bots only.