Configuration

The init command accepts a configuration object. Start with minimal settings, then add options as needed.

For the full host API model (layers, page-based context, runtime methods), see Host Integration API.

Usage

window.LoopsAI.q.push([
  "init",
  {
    agentId: "YOUR_AGENT_ID",
    position: "bottom-left",
    theme: "dark",
    width: 400,
    height: 600,
    defaultLocale: "en",
    userContext: {
      id: "user-123",
      email: "user@example.com",
    },
  },
]);

Required option

Common options

Keep it simple

For most teams, these are enough:

1. agentId
2. position
3. theme
4. productContext and userContext when available

Custom search / Ask AI button

If you build your own search bar and Ask AI control, call LoopsAI.openWithSearch(query) on click — keep the built-in injection off so two buttons don't appear. See Custom Ask AI Search Button.

Product page sidebar (PDP)

To show the widget as a side panel on product detail pages, pass openAsSidebarOnProduct: true in your init config together with productContext.pageType: "PDP" on the product pages where you want it. You control this per page in code — the same setting exists in the configurator only as a testing convenience. Opening the panel still uses LoopsAI.open() unless the user arrives with ?loopsai_open=sidebar. See Host Integration API for the full PDP tutorial.

See Product & User Context for full PDP sidebar examples (full page load, SPA updates, and custom CTA).

Widget status and staging environments

Active / Inactive

Every web channel has an Active / Inactive toggle in the Loops AI dashboard (under Channels → Web → Status). When a channel is set to Inactive, the CDN configuration carries embedEnabled: false and the embed script exits immediately — no widget appears on the page, no iframe is created.

This lets you:

• Keep the widget hidden on production while you finish configuring it.
• Roll it out gradually by switching it on when ready.
• Temporarily disable the widget without touching your site's code.

Web only. This Active / Inactive toggle controls the web channel. The iOS and Android SDKs are enabled independently under Channels → iOS and Channels → Android — see Enabling & disabling chat.

Preview on a staging site with developmentMode

When you're testing on a staging or preview environment, you often want the widget to appear even though the production channel is still inactive. Pass developmentMode: true in your init call to override the channel status check:

window.LoopsAI.q.push([
  "init",
  {
    agentId: "YOUR_AGENT_ID",
    developmentMode: true, // widget loads even when the channel is inactive
  },
]);

Typical workflow

Hide the widget on specific pages (e.g., checkout)

Want the assistant available across your store but not on the purchase / checkout screen? Send embedEnabled: false in init only on that page — it overrides the dashboard's Active/Inactive setting for that page load without touching the channel itself:

const hideOnThisPage = /^\/checkout|^\/cart/.test(window.location.pathname);

window.LoopsAI.q.push([
  "init",
  {
    agentId: "YOUR_AGENT_ID",
    embedEnabled: !hideOnThisPage,
  },
]);

This works when checkout is its own page load. If your agent uses the injected Ask AI search button, also set searchButtonEnabled: false and searchEscalationEnabled: false on that page (that feature boots independently of embedEnabled). If your storefront is a single-page app where checkout is just a client-side route (no reload), see the full pattern — including how to keep the conversation alive in the background — in Host Integration API → Hide the widget on specific pages.

Continue to Product & User Context.