Javascript Sdk

JavaScript SDK

Boei's SDK allows you to dynamically configure and customize your Boei widget. Here's how to use it:

How to get there: Go to Setup → Widget in the top menu → click your widget to get your widget ID.

Setup

First, include the Boei initialization code in your script:

window.BQ=window.BQ||[];window.Boei=window.Boei||function(u){BQ.push(u)};

Pre-setting Visitor Information

Pre-fill visitor contact info so they don't have to enter it manually:

Boei({
    name: 'John Doe',
    email: 'john@example.com',
    phone: '+1234567890',
    company: 'Acme Inc',
    id: 'customer-123',
    notes: 'VIP customer'
});

You can also set fields individually:

Boei({name: 'John Doe'});
Boei({email: 'john@example.com'});

Pre-setting Chatbot Tags

Pre-set tags to filter chatbot knowledge base content (skips the pre-chat tag question flow):

Boei({tags: 'tag-slug-1,tag-slug-2'});

Widget Settings

Use Boei() to modify global settings:

Boei({brand_background: 'green'});

Key Variables:

• brand_background: Set the background color of the widget
• brandcolor: Set the primary brand color
• brandcolor_text: Set the text color for brand elements
• button_hover_label: Set the label that appears on button hover
• position: Set the widget position ('bottom_left', 'bottom_right', 'top_left', 'top_right')
• shape: Set the widget shape ('circle', 'square')

Adding Channels

Add new channels to your widget:

Boei({add_channel: {
    type: "link",
    title: "External Website Link",
    url: "https://boei.help",
    options: {
        new_window: true,
        custom_conversion_label: 'Custom' // Can be null for default
    },
    position: 2 // The position in the widget
}});

Channel Properties:

• type: Channel type (e.g., "link", "form", "chat")
• title: Display title for the channel
• url: URL for link channels
• options: Additional settings (optional)
  • new_window: Open link in new window (boolean)
  • custom_conversion_label: Custom label for conversion tracking
• position: Position in the widget (integer)

Controlling the Widget Programmatically

Boei exposes a small set of methods you can call to open, close, and interact with the widget from your own JavaScript. These are useful for hooking the widget up to your own buttons, form submissions, search bars, route changes, or analytics events.

Open and close

Boei.open();              // open the widget
Boei.open('whatsapp');    // open straight into a specific channel by key
Boei.close();             // close the widget panel
Boei.isOpen();            // returns true / false

The channel key is the one you set in the channel's settings inside your widget.

Hide and show the launcher button

If you want full control over when the widget appears (for example only after a custom button is clicked), you can hide the launcher entirely and show it again later:

Boei.hideLauncher();
Boei.showLauncher();

Start a chatbot conversation with a pre-filled question

Boei.ask(message) opens the chatbot and sends message as the first user message automatically. This is great for turning a search bar, a "ask AI" link, or a help-page CTA directly into a live conversation.

Boei.ask('How do I install Boei on WordPress?');

If your widget has multiple chatbots, pass the chatbot's channel key as a second argument:

Boei.ask('How do I install Boei on WordPress?', 'support-bot');

Notes:

• If a conversation is already in progress, the pre-filled message is ignored so it doesn't barge in mid-chat.
• If the widget has no chatbot channel, the call is a no-op and a warning is logged to the console.

Passing visitor info before opening

If you know the visitor's name, email, etc. (for example because they're already logged in to your site), set it first and then open the widget so the chatbot and any forms have it pre-filled:

Boei({ name: 'Jane Doe', email: 'jane@example.com' });
Boei.open();
// or
Boei({ name: 'Jane Doe', email: 'jane@example.com' });
Boei.ask('What plan should I be on?');

See Pre-setting Visitor Information above for the full list of supported fields.

Advanced: full widget instance access

If you need access to internals that aren't exposed by the flat API, pass a function to Boei() to get a reference to the live widget instance:

Boei(function (widget) {
    // widget.* full access
});

The callback runs as soon as the widget is mounted, or is queued if you call it before the widget script has loaded.

See Custom Trigger for non-JS ways to open the widget (CSS class, URL parameter, etc.).

Multiple changes

You can chain multiple configurations:

Boei({brand_background: 'green'});
Boei({add_channel: {...}});
Boei({button_hover_label: 'Need Help?'});

Remember, settings are applied in the order they are called, with later calls potentially overwriting earlier ones.

List of Editable Variables

Here's a comprehensive list of variables you can edit using Boei SDK:

General Appearance

• brand_background: Background color or gradient for the widget
• brandcolor: Primary brand color
• brandcolor_text: Text color for brand elements
• button_hover_label: Label that appears on button hover
• position: Widget position ('bottom_left', 'bottom_right', 'top_left', 'top_right')
• shape: Widget shape ('circle', 'square')
• opacity: Widget opacity (0 to 1)
• button_icon_size: Size of the button icon
• button_width: Width of the button
• button_height: Height of the button
• button_margin_x: Horizontal margin for the button
• button_margin_y: Vertical margin for the button

Widget Behavior

• trigger_after_seconds: Time in seconds before triggering the widget
• trigger_message: Message to display when widget is triggered
• trigger_message_only_new_visitor: Show trigger message only for new visitors (boolean)
• close_trigger_after_seconds: Time in seconds before closing the trigger message
• auto_open_after_seconds: Time in seconds before automatically opening the widget
• auto_open_only_new_visitor: Auto-open only for new visitors (boolean)
• notification_badge_after_seconds: Time in seconds before showing a notification badge
• glow_after_seconds: Time in seconds before applying a glow effect
• glow_duration_seconds: Duration of the glow effect in seconds
• glow_color: Color of the glow effect

Customization

• custom_css: Custom CSS to apply to the widget
• icon_svg: Custom SVG icon for the widget button
• button_image: Custom image for the widget button
• close_src: Custom image for the close button
• loading_src: Custom loading image

Functionality

• test_mode: Enable test mode (boolean)
• allow_identifiers: Allow user identifiers (boolean)
• direct_open_when_one_channel: Directly open single channel (boolean)
• display_button_watermark: Show button watermark (boolean)
• display_helper_watermark: Show helper watermark (boolean)
• display_close_trigger_message: Show close button on trigger message (boolean)
• display_countdown_timer: Show countdown timer (boolean)
• display_countdown_timer_seconds_left: Seconds left for countdown timer
• hide_on_pages: List of pages to hide the widget on
• is_spa: Treat as Single Page Application (boolean)

Analytics and Integrations

• use_google_analytics4: Use Google Analytics 4 (boolean)
• use_plausible_analytics: Use Plausible Analytics (boolean)
• use_google_tag_manager: Use Google Tag Manager (boolean)
• use_simple_analytics: Use Simple Analytics (boolean)
• use_facebook_pixel: Use Facebook Pixel (boolean)

Chatbot / Visitor

• name: Pre-fill visitor name
• email: Pre-fill visitor email
• phone: Pre-fill visitor phone
• company: Pre-fill visitor company
• id: Pre-fill visitor ID (for CRM integration)
• notes: Pre-fill visitor notes
• tags: Comma-separated tag slugs for KB filtering

Channel-specific (used with add_channel)

• type: Channel type (e.g., "link", "form", "chat")
• title: Display title for the channel
• url: URL for link channels
• options: Additional channel-specific options
  • new_window: Open link in new window (boolean)
  • custom_conversion_label: Custom label for conversion tracking

Remember, not all variables may be applicable to every use case.