Embedding Alhena's chat widget takes two lines of code. What most teams don't realize is that those two lines unlock over 40 appearance settings, a full runtime JavaScript API, four distinct embed modes for live chat, and a behavioral event stream and full SDK for chatbots. The SDK gives developers that you can pipe straight into your analytics stack. Here’s every lever, organized by what it controls.
The Two-Line Embed and What It Actually Does
The standard chat embed code looks like this:
<script>
document.gleenConfig = { company: "your-company-key" };
</script>
<script src="https://app.gleen.ai/sdk/gleenWidget.js"></script>That script reads your config, calls Alhena's API to pull every styling and behavior setting from your dashboard, injects a mount point, and boots the live chat widget. Everything after that is configuration you can customize and configure, either in the dashboard, in document.gleenConfig, or through the runtime JS API window.gleenWidget.
Appearance: 40+ Knobs for Look and Feel
The dashboard's Widget Customization page exposes granular control over how customizable live chat widgets look on your site. You can modify every visual element, from tagline to colors.
Colors cover 13 separate tokens: widget background, header background and text, user message bubble and text, bot message bubble and text, send button, launcher background and text, suggested-questions background and text , nudge background for live chat, and CTA button color that renders . Every surface has its own token, so chat widgets can match your digital design system exactly, so your widget can match your design system exactly.
Typography includes font family (any CSS font, including web fonts), message font size, and line height. Logos and avatars allow you to set a brand logo and display name in the header; a bot avatar with a display name on messages to personalize the chat support experience; and a separate email transcript logo for emailed conversation history.
Geometry controls widget width, border radius, launcher shape (choose circle or square), launcher icons and icon size, close button style (chevron, cross, or dash that you can disable), and UI z-index for both the panel and launcher, . For live chat, that last one matters more than you'd think: sites with sticky headers or cookie banners often bury the widget under other elements. Separate desktop, mobile apps, and mobile spacing settings allow you to position the launcher differently on each device, and a mobile launcher size setting for thumb-zone reach.
Behavior and Content Settings
Beyond appearance, the widget's behavior customization lets you customize how it's configurable at a granular level. You can set a live chat window home screen title, subtitle, and tagline for the greeting panel , two staged welcome messages with a display name that appear as bot bubbles, and separate launcher text for desktop and mobile. Input placeholder text, auto-close timing with a custom closing message, and satisfaction prompt delay are all adjustable through the user interface or dropdown menus in the UI.
For teams running human handoff through Alhena's live chat Support Concierge, you can customize and configure separate business hours versus after-hours custom chat support form fields with dropdown selectors per path (require email plus order number during hours; add phone after hours) and timezone-aware scheduling. You can toggle whether "assigned to Jane" messages show to the customer at all and enable anonymous agent mode to hide the display name and real names.
The Runtime JS API Most Integrators Miss
window.gleenWidget is a full programmatic surface to modify widget behavior that goes well beyond open and close for your live chat.
Open, close, toggle: gleenWidget.open({ expanded: true }), gleenWidget.close(), gleenWidget.toggle(). When the chat window opens you can also hide or show the launcher independently, a way to customize visibility, useful for suppressing the bubble on checkout while keeping it available through your own button.
User context for personalization: The live chat SDK method gleenWidget.setUserMetadata("plan", "enterprise") passes user information like display name to personalize responses the AI uses for routing and custom prompts. Pair that with gleenWidget.getFingerprint() to link anonymous chat sessions to a logged-in user later and view the full conversation history.
Programmatic messaging: The SDK call gleenWidget.sendMessage("Where is my order?") allows you to trigger live chat conversations from any UI element or window. getMessages() and getTicketId() give you read access to the current session.
Commerce hooks: sendCartEvent(cart) and sendCheckoutEvent(checkout) feed real time live chat cart data to the AI. setConvertPriceHook(fn) handles custom currency and locale formatting for Shopify and headless storefronts. For multi-brand portals, setCompanyKey("other-brand-key") switches the entire widget config on the fly.
Four Embed Modes, Not One
The floating launcher is the default, but you can choose from three other embedded modes, each renders a different version of the widget for specific UI use cases.
- Floating launcher: The standard chat bubble. Works for general browsing across your site.
- Inline mode: Mount the chat into any container via
<div id="helix-chat-container">. Ideal for help center pages and the best option for dedicated customer support hubs. It’s also the best way to surface chatbot answers where the chat interface should be a persistent, visible element rather than a hidden bubble. - Product FAQs widget: Drop
<div id="gleen-product-faqs"></div>on any PDP for a contextual Q&A module. It has its own independent theming system (container, card, selected state, answer, and input surfaces are all separately styleable). - Conversational Search:
<div id="alhena-conversational-search"></div>renders a search box with starter questions.openSearch("laptop")programmatically opens it with a prefilled query.
Each mode has its own color palette, starter questions, and placeholder text, and can be A/B tested, configured, and customized through the live chat UI independently. To learn how to place these across Shopify, WooCommerce, and other e-commerce composable storefronts, see the headless commerce guide.
Nudges: The Right Message on the Right Page
A nudge renders as a tooltip-style bubble that pops from the launcher to pull visitors into conversation. Alhena's nudge system offers two trigger types for nudge customization: TIMER (after N seconds) and SCROLL (after N pixels of scroll depth).
Targeting conditions match PAGE_URL or PAGE_TITLE with equals, not-equals, contains, or not-contains operators. A rule like PAGE_URL CONTAINS "/collections/" matches every collection page for live chat targeting. PAGE_TITLE NOT_CONTAINS "checkout" suppresses nudges during purchase.
Content can be fixed text (with multiple rotating variations) or AI-generated, where you give the bot guidelines and it writes page-contextual chat nudge copy automatically. UI display controls include tagline text, max nudges to rotate, and you customize, animation interval, window position ,, button label, background shade, corner radius, and priority ranking. Cap frequency at one or two nudges per session to avoid fatigue.
Events: Everything Is Observable
gleenWidget.on(event, callback) supports a rich event stream you can pipe into GA4, Segment, Mixpanel, your CRM, or Hotjar.
- Lifecycle:
widget:loaded,widget:opened,widget:closed - Conversation:
ticket:message_submitted,ticket:bot_response_finished,ticket:link_clicked,ticket:attachment_added,ticket:closed - Handoff:
ticket:agent_handoff_initiated,ticket:agent_handoff,ticket:email_submitted - Commerce:
product:added_to_cart,products:added_to_cart,product:page_opened,product:displayed - FAQ/search:
faqs:question_clicked,faqs:bot_response_finished - Experiments:
experiment:loaded
This makes the widget a first-class live chat analytics source of behavioral insights and telemetry, not a black box, . Wire these into your analytics to track which PDPs generate the most chat-initiated cart additions, which nudge variants drive the highest open rates, and where agent handoffs cluster by product category.
Privacy, Consent, and Localization
A privacy consent banner with custom text must be accepted before chatting begins. You must enable attachment consent, which is a separate opt-in before file uploads. You can modify consent text freely. The display name, branding, and whitelabel mode remove Alhena branding entirely, and a custom_js field runs your own code inside the widget on load for advanced integrations.
Localization auto-detects the user's browser locale. All consent text, welcome messages, and launcher text can be overridden per locale, so visitors choose their preferred language, with a fallback chain from the requested locale to English. The UI locale matches the AI's multilingual answering, so the entire live chat experience stays consistent.
For Shopify and WooCommerce stores, the live chat widget installs via a single app or plugin. For headless builds on Salesforce Commerce Cloud or custom frontends, the two-line embed plus the latest version of the SDK and JS API gives you full control without waiting on a dev sprint. The widget design and conversion optimization guide covers how placement and trigger decisions connect to measurable revenue outcomes.
Ready to go beyond the default embed? Book a demo with Alhena AI to see these live chat customizations on your site, or start free with 25 conversations.
Frequently Asked Questions
How do I embed the Alhena chat widget on my website?
Add two lines of JavaScript to your site to embed the chatbot: a config object with your company key. It’s the fastest way to add customer support chat to any site and the widget script tag. The script pulls all styling and behavior settings from your Alhena dashboard automatically. No build step or framework dependency required.
What appearance settings can I customize in the Alhena widget?
Over 40 settings are available: 13 color tokens (backgrounds, text, bubbles, buttons), font family and size, brand logo and bot avatar, widget width, border radius, launcher shape, close button style, z-index, and separate desktop and mobile spacing. Everything is editable from the dashboard.
What is the window.gleenWidget JS API?
It's a runtime JavaScript API that gives you programmatic control over the widget. You can open, close, and toggle the chat, send user metadata for personalization, trigger messages, pass cart and checkout events, track responses, switch company keys for multi-brand setups, and get the visitor fingerprint for session linking.
What are the different embed modes available?
Four chatbot embed modes: floating launcher (the standard bubble), inline mode (mounted into any page container), Product FAQs widget (contextual Q&A on PDPs with independent theming), and Conversational Search (a search box with starter questions). Each has its own color palette and configuration.
How do nudges work in the Alhena widget?
Nudges are tooltip bubbles triggered by timer or scroll depth, targeted by PAGE_URL or PAGE_TITLE conditions. Content can be fixed text with rotating variations or AI-generated from page context. One nudge per session lifts conversions 15-25%. Display controls include animation interval, background shade, and priority ranking.
Can I track chat widget events in Google Analytics or Segment?
Yes. The gleenWidget.on(event, callback) API supports 20+ events across lifecycle, conversation, handoff, commerce, and FAQ categories. Pipe widget:opened, product:added_to_cart, and ticket:agent_handoff into GA4, Segment, Mixpanel, your CRM, or Hotjar. Brands use this data to measure chat-initiated revenue, handoff rates by category, and which nudge variants perform best.
Does the widget support multiple languages?
Yes. Localization auto-detects the browser locale. All consent text, welcome messages, and launcher text can be overridden per language with a fallback chain to English. The UI language syncs with the AI's multilingual answering so the entire experience stays consistent.
