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>

Codes with a region are reduced to the language automatically: en-GB, EN or en_GB all count as en.

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 tells the assistant which page the user is on and what that page is about. It is always on and needs no setup: with every message, the widget sends the address, title and description of the current page on its own.

This data helps the assistant 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 assistant know which page the user is looking at and, when needed, tailor its answer accordingly.

What is read automatically

All three fields are read again when the chat opens, when the user focuses the text field and on every send, so they stay current even when the page changes without reloading.

Overriding the fields

If the automatic values aren’t enough — say the meta description is generic, or identical on every page — you can supply one or more fields yourself with pageContext in IKIbrainConfig, before the embed script. The fields you pass replace the ones read from the page; the rest are still detected automatically.

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

In most cases description is all you need: it’s the most useful field for telling the assistant what the user is looking at (product name, service, category, etc.). You can override url and title the same way.

Turning it off

If you’d rather the assistant received no information about the page, set pageContext to false:

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

You can do the same at runtime with IKIbrainWidget.setPageContext(false).

Custom descriptions 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.

With automatic reading there is nothing you need to do: address, title and meta description are read again with every message and follow route changes. IKIbrainWidget.setPageContext() is only for when you want a description of your own that changes with the page, since one defined in IKIbrainConfig stays the same for the whole visit:

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

// To go back to automatic reading
IKIbrainWidget.setPageContext(null);

The new context applies to every subsequent message. Fields you don’t pass are still read from the current page. setPageContext(null) drops your values and goes back to automatic reading: it does not switch the context off (use false for that).

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 assistant 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), there’s no need to repeat it in every call: call openWithQuestion() with just the question and the assistant relies on the page context. If the meta description already describes the product you’re done; otherwise declare your own description once:

<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>

Button context and page context

The 2nd argument of openWithQuestion(question, context) and the page context add up; one does not replace the other. The button context steers the search for the answer to the question that opens the chat; the page context is still sent and stays available to the assistant for the whole conversation.

<!-- Page context: "Ergonomic Chair XR-500" -->

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

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

A question is sent with no context at all only if you have turned page context off with pageContext: false and pass no context parameter: the assistant then receives just the question text, and contextual questions (e.g. "what material is it made of?") may be ambiguous.

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: {         // Fields that override automatic reading (false to turn it off)
    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