Documentation

Configuration

Customize the widget appearance and behavior via the admin panel or JavaScript config.

Admin panel configuration

The easiest way to configure the widget is through the admin panel at Admin → Widget. From there you can set:

Theme color — primary color for the widget button and header.
Position — bottom-left or bottom-right.
Welcome message — the first message visitors see when they open the widget.
Pre-chat form fields — require name, email, or phone before starting a chat.
Offline message — shown when no agents are available.
Operating hours — automatically toggle between online and offline modes.

JavaScript overrides

Define a window.__bxlivechat object before the widget script loads to override configuration at the page level.

config.js

window.__bxlivechat = {
  orgId: "YOUR_ORG_ID",

  // Position & layout
  position: "right",       // "left" or "right"
  offsetX: 20,             // horizontal offset in px
  offsetY: 20,             // vertical offset in px

  // Locale
  language: "auto",        // en | th | zh | ja | ko | pt | "auto"

  // Pre-fill visitor info
  visitor: {
    name: "Jane Doe",
    email: "[email protected]",
    phone: "+1-555-0100",
  },

  // Arbitrary data visible to agents
  customData: {
    plan: "enterprise",
    accountId: "acct_8xk29z",
  },

  // Behavior
  hideOnMobile: false,
  disableSound: false,
};

All config options

Parameter	Type	Description
`orgId`*	`string`	Your workspace ID from the admin panel.
`position`	`string`= "right"	Widget button position: "left" or "right".
`offsetX`	`number`= 20	Horizontal offset from the edge of the viewport in pixels.
`offsetY`	`number`= 20	Vertical offset from the bottom of the viewport in pixels.
`language`	`string`= "auto"	Widget UI language. Supported: en, th, zh, ja, ko, pt. Set to "auto" to detect from the browser.
`visitor.name`	`string`	Pre-fill the visitor name to skip the pre-chat form field.
`visitor.email`	`string`	Pre-fill the visitor email.
`visitor.phone`	`string`	Pre-fill the visitor phone number.
`customData`	`object`	Arbitrary key-value pairs displayed to agents in the chat sidebar.
`hideOnMobile`	`boolean`= false	Hide the widget on viewports narrower than 480px.
`disableSound`	`boolean`= false	Mute all notification sounds from the widget.

Admin overrides

Admin panel settings like theme color, welcome message, and pre-chat form fields always take precedence over JavaScript config for visual consistency.

Installation JavaScript API