Owlish Docs

Web widget

Embed the chat widget on your website. Configure allowed domains, citations, and customization on the agent's Channels and Playground pages.

The web widget is the most common way Owlish ships in front of customers — a floating chat bubble that opens to a panel on your site. It’s available on every plan and works on any website.

Where widget configuration lives

Widget settings are split across two pages on the agent:

  • Playground — visual customization (Brand, Content, Behavior tabs). See Customize the widget.
  • Channels → Web widget — domain allowlist and channel-specific toggles like citation display.

Channels page settings

Open the agent → Channels → Web widget to configure:

  • Allowed domains — a list of domains where the widget is allowed to load. Requests from other origins are rejected. Add every production domain you’ll embed on, plus any staging domains for testing.
  • Enforce allowed domains — toggle. When on, requests from non-listed origins are rejected. Turn off temporarily for development if needed; turn back on for production.
  • Citation config — whether to show source citations on agent answers in the widget. On by default.
Web widget channel settings with embed snippet, allowed domains, enforcement, and source citation controls.

Embed on your site

The embed snippet is generated per agent and is provided in the Channels page. Paste it before </body> on every page where the widget should appear (or via your tag manager).

Common destinations:

  • Plain HTML site — paste before </body> on every page.
  • WordPress — use a “Header / Footer scripts” plugin or paste in your theme’s footer.
  • Shopify — Theme → Customize → “Add custom code” before </body>.
  • Tag manager (GTM, Segment, etc.) — wrap in a Custom HTML tag with a page-load trigger.

The widget loads asynchronously and won’t block your page.

Keep the launcher clear of your site controls

Visitors can drag the closed launcher to another part of the viewport. Its position is saved for that agent on the current site, and keyboard users can focus it and use Alt + arrow keys to move it or Alt + 0 to reset it.

If your site has a fixed footer, cookie control, or another bottom-corner action, set safe default offsets on the embed:

<script
  src="https://widget.owlish.bot/loader.js"
  data-agent-id="agt_xxx"
  data-side-offset="24"
  data-bottom-offset="88"
  defer>
</script>

Both offsets are pixels. The launcher still remains movable after these defaults are applied. A host application can also restore the configured default with window.OwlishWidget.resetPosition().

Visual customization

For the visual side — colors, logo, welcome message, suggested questions — all of that is on the agent’s Playground page rather than the Channels page. See Customize the widget for which tab each setting lives on.

Next steps