Widget

Hide Launcher

If you want to control when and how the chat opens (e.g. only from custom buttons), you can hide the default floating icon.

Add the IKIbrainConfig object before the embed script:

<script>
window.IKIbrainConfig = { hideLauncher: true };
</script>
<!-- embed code here -->

When the launcher is hidden, the chat can only be opened programmatically via the JavaScript API described below.

Multilingual Sites

If the bot is configured for multiple languages, the widget normally shows a language selection screen when the user opens it. On a multilingual website, you already know which language the user is browsing in — you can skip that screen by passing lang in IKIbrainConfig:

<script>
window.IKIbrainConfig = { lang: 'it' };
</script>
<!-- embed code here -->

The widget will open directly in the specified language, skipping the selection panel entirely.

How to set the language dynamically

On a site where the language comes from a PHP variable, a data- attribute, or a JS constant, pass it inline:

<!-- PHP example -->
<script>
window.IKIbrainConfig = { lang: '<?= htmlspecialchars($currentLang) ?>' };
</script>

<!-- JavaScript example -->
<script>
window.IKIbrainConfig = { lang: document.documentElement.lang || 'en' };
</script>

Supported language codes

Open / Close

You can open or close the chat window programmatically:

// Open the chat window
IKIbrainWidget.openChat();

// Close the chat window
IKIbrainWidget.closeChat();

Example with a custom button:

<button onclick="IKIbrainWidget.openChat()">
  Chat with us
</button>

Auto Open

By default the widget loads closed and the user clicks the launcher to open the chat. With autoOpen you can show the chat already open when the page loads. Like the other options, it must be defined in IKIbrainConfig before the embed script:

<script>
window.IKIbrainConfig = { autoOpen: true };
</script>
<!-- embed code here -->

On mobile the open chat takes over the full screen, which can feel intrusive on first load. If you prefer auto-opening on desktop only, use the 'desktop' value:

<script>
window.IKIbrainConfig = { autoOpen: 'desktop' };
</script>
<!-- embed code here -->

Supported values

Chat Position

By default the chat window opens at the bottom of the page (right, left or — with the bar launcher — centered, depending on the bot configuration). If you hid the launcher to use your own icon somewhere else on the page, chatPosition lets you open the panel next to it:

<script>
window.IKIbrainConfig = {
  hideLauncher: true,
  chatPosition: { bottom: '96px', left: '24px' }
};
</script>
<!-- embed code here -->

Supported properties

Values accept the most common CSS units (px, %, rem, em, vh, vw) or plain numbers, interpreted as pixels. Invalid values are ignored. If you specify only one axis, the other keeps its default.

The opening animation adapts automatically to the chosen position: with a bottom anchor the panel slides up from below, with top it slides down from above, and the effect origin follows the side (left or right) it is anchored to.

Page Context

Page context lets the bot know which page the user is on and what that page is about. It is a global context: once enabled, it is inherited automatically by every message in the session, so you don't have to repeat it on each button.

Enabling it

Page context is not active by default: this means the bot doesn't know which page the user is on. To turn it on you have to enable it explicitly, by defining window.IKIbrainConfig with a pageContext key before the embed script:

<script>
  window.IKIbrainConfig = { pageContext: {} };   // ← this is the line that turns it on
</script>
<!-- embed code here -->

Supported values

You can also set the pageContext fields manually:

<script>
  window.IKIbrainConfig = {
    pageContext: {
      url: 'https://www.example.com/chairs/xr-500',
      title: 'Ergonomic Chair XR-500',
      description: 'Ergonomic Chair XR-500 - Office Seating, adjustable backrest, 5-year warranty'
    }
  };
</script>
<!-- embed code here -->

In most cases description is all you need: url and title are detected automatically from the current page.

This data helps the bot answer better in two ways:

1. it helps interpret the user's contextual questions — e.g. "what material is it made of?" — which without context would have no clear subject;
2. it lets the bot know which page the user is looking at and, when needed, tailor its answer accordingly.

Updating the context on SPA sites

SPA stands for Single Page Application: a type of site (typically built with React, Vue, Angular, Next.js, Svelte, etc.) where navigation between pages happens without a browser reload. The URL changes and the content is swapped via JavaScript, but the widget script stays loaded for the whole visit.

This means the pageContext defined in IKIbrainConfig is read only once, when the site opens, and does not automatically update on route changes. To update the context when the user navigates, call IKIbrainWidget.setPageContext():

// On route change
router.afterEach(function (to) {
  IKIbrainWidget.setPageContext({
    description: 'Page ' + to.meta.productName
  });
});

// To reset
IKIbrainWidget.setPageContext(null);

The new context applies to every subsequent message. url and title auto-populate from the current page if not passed explicitly.

function ikiReady(fn) {
  if (window.IKIbrainWidget) { fn(); }
  else { setTimeout(function () { ikiReady(fn); }, 100); }
}

router.afterEach(function (to) {
  ikiReady(function () {
    IKIbrainWidget.setPageContext({ description: 'Page ' + to.meta.productName });
  });
});

Open with Question

The most powerful feature: open the chat with a pre-defined question, leveraging the page context. The bot will answer as if the user had typed the question, with full awareness of what page the user is on.

IKIbrainWidget.openWithQuestion(question, context)

Example:

<button onclick="IKIbrainWidget.openWithQuestion(
  'What material is this made of?',
  'Ergonomic Chair XR-500 - Office Category'
)">What material is this made of?</button>

Multiple buttons, same context

When a page has multiple buttons sharing the same context (e.g. several questions about the same product), instead of repeating it in every call you can declare it once in the global page context: every button inherits it and you call openWithQuestion() with just the question.

<script>
window.IKIbrainConfig = {
  pageContext: {
    description: 'Ergonomic Chair XR-500 - Office Furniture'
  }
};
</script>
<!-- embed script here -->

<button onclick="IKIbrainWidget.openWithQuestion('What material is it made of?')">Materials</button>
<button onclick="IKIbrainWidget.openWithQuestion('Which sizes are available?')">Sizes</button>
<button onclick="IKIbrainWidget.openWithQuestion('What is the warranty?')">Warranty</button>

Precedence rule

The 2nd argument of openWithQuestion(question, context) always wins over the global context. If a button passes an explicit non-empty context, it overrides the global value; otherwise the global pageContext is used as fallback.

<!-- Global: "Ergonomic Chair XR-500" -->

<!-- Uses the global context -->
<button onclick="IKIbrainWidget.openWithQuestion('How much does it weigh?')">Weight</button>

<!-- Overrides with a specific context -->
<button onclick="IKIbrainWidget.openWithQuestion(
  'What is the return policy?',
  'Store-wide return policy'
)">Returns</button>

If neither a global context nor the context parameter is set, the question is sent without any page context: the bot only receives the question text and doesn't know which page the user is on. Contextual questions (e.g. "what material is it made of?") may then be ambiguous, since the reference to the product or page content is missing.

Example: E-commerce Product Page

On a product page, declare the context once and add contextual buttons that ask common questions about that product:

<script>
window.IKIbrainConfig = {
  hideLauncher: true,
  pageContext: {
    description: 'Ergonomic Chair XR-500 - Office Furniture'
  }
};
</script>

<!-- Product: Ergonomic Chair XR-500 -->
<div class="product-questions">
  <button onclick="IKIbrainWidget.openWithQuestion('What material is this made of?')">Materials</button>
  <button onclick="IKIbrainWidget.openWithQuestion('Is this available in other sizes?')">Sizes</button>
  <button onclick="IKIbrainWidget.openWithQuestion('What is the warranty on this product?')">Warranty</button>
</div>

Example: Real Estate Listing

<button onclick="IKIbrainWidget.openWithQuestion(
  'How much is the monthly rent?',
  '3-bedroom apartment, Via Roma 15, Milan - Ref. APT-2024-089'
)">Ask about rent</button>

<button onclick="IKIbrainWidget.openWithQuestion(
  'Is there a garage available?',
  '3-bedroom apartment, Via Roma 15, Milan - Ref. APT-2024-089'
)">Ask about parking</button>

Example: Service Page

<button onclick="IKIbrainWidget.openWithQuestion(
  'How much does this service cost?',
  'SEO Audit & Optimization - Digital Marketing Services'
)">Ask about pricing</button>

<button onclick="IKIbrainWidget.openWithQuestion(
  'How long does it take?',
  'SEO Audit & Optimization - Digital Marketing Services'
)">Timeline</button>

API Reference

Configuration Object

window.IKIbrainConfig = {
  hideLauncher: true,    // Hide the floating chat icon
  autoOpen: true,        // Open the chat on page load (true or 'desktop')
  chatPosition: {        // Chat panel position (default: bottom corner)
    bottom: '96px', left: '24px'
  },
  lang: 'it',           // Skip language selector (multilingual bots)
  pageContext: {         // Global page context (inherited by every message)
    description: 'Ergonomic Chair XR-500'
  },
  serviceContext: {...}  // External service context (advanced)
};

The IKIbrainConfig object must be defined before the embed script loads.

serviceContext (advanced)

If your site runs its own application — user accounts, carts, orders — the assistant can take session data from it so that its actions adapt to the current user or session (for example: enabling actions only for logged-in users, or cart-aware features).

This is an integration-level feature: the exact data passed and how it's used are configured together with us and depend on your setup. It is meant for powering actions, not for user authentication.

Behavior Details

Session Management

• Each openWithQuestion() call starts a new, clean session
• If the chat is already open, the current session is reset before starting the new one
• The onboarding flow (privacy notice, language selector, OTP, pre-chat form) runs normally before the question is sent

Multiple Buttons

• If the user clicks multiple buttons quickly, only the last one wins
• Each button can use different questions but share the same context, or vice versa

Context Tips

• Be descriptive — include the product/service name, category, and any unique identifier
• Keep it concise — aim for 10-50 words. This is not a full page description, just enough for the bot to identify what the user is looking at
• Use consistent naming — match the terminology used in your knowledge base for best results

Compatibility

• Works on all modern browsers (Chrome, Firefox, Safari, Edge)
• The standard widget behavior is fully preserved when hideLauncher is not set
• All existing features (multilingual, pre-chat forms, OTP for private bots) work normally