Website widget

Install the Asks chat widget on your site with one script tag, as a floating launcher or an inline embed.

View as Markdown

The website widget is the flagship channel: a chat launcher on your own site where visitors talk to your AI agent, and your team can step in from the Inbox. A widget is created for you during onboarding — this page covers turning it on and installing it. How it looks and behaves is covered in Widget customization.

You manage the widget at Channels → Website Widget. The page header carries the master toggle: flip it and the status pill switches between Live and Off. While the widget is off it doesn't load on your site, and the install snippets on the Deploy tab dim with a note asking you to enable the widget first.

Website Widget page header with the Live status pill, the master toggle switched on, and the Content, Style, Behavior, Deploy tab strip above the settings form, with the live preview on the right — The master toggle and tab strip in the page header.

Open the Deploy tab. A switcher offers three surfaces — Widget, Embed, and Chat Page. Pick Widget, copy the embed code, and paste it into your site before the closing </body> tag:

HTML

<script
  src="https://cdn.asks.app/embed.js"
  data-widget-key="YOUR_WIDGET_KEY"
  async
></script>

The snippet on the Deploy tab already contains your real widget key — copy it from there rather than editing this example.

Deploy tab with the Widget, Embed, and Chat Page switcher, the Widget surface selected, the embed code card with a Copy button, and the live preview on the right — The Deploy tab with the Widget surface selected.

Paste the embed code before the closing </body> tag of your HTML file. It works on any static site or site builder that lets you add custom HTML.

Verify it works — open your site in a new tab and look for the launcher in the corner. Send a test message; it appears as a conversation in your Inbox, and if the agent is enabled for the widget under AI agent → Deploy, you get an instant reply.

Inline embed mode

Instead of a floating launcher, you can render the chat inside a section of your page — useful for a dedicated contact or support page. Pick the Embed surface on the Deploy tab and paste the snippet where the chat should appear:

HTML

<div id="asks-widget-embedded" style="width:100%;height:600px;"></div>
<script src="https://cdn.asks.app/embed.js" data-widget-key="YOUR_WIDGET_KEY" data-container-id="asks-widget-embedded" async></script>

The chat fills the container (600px tall by default). Size it with the container itself, or with the widget's max width and height under Style → Window size.

Programmatic control

The loader exposes a small API on window.AsksWidget:

AsksWidget.open() / AsksWidget.close() — open or close the floating panel, for example from your own "Chat with us" button.
AsksWidget.init({ widgetKey, containerId }) — mount manually instead of through the script tag's data attributes. For inline mode, targetSelector accepts any CSS selector as an alternative to containerId.
AsksWidget.version — the build identifier of the script actually running on the page.

The script tag also accepts optional identity hints for logged-in visitors — data-customer-email, data-customer-name, and data-shopify-customer-id. They personalize the conversation but are never treated as authentication. The Shopify theme embed sets them automatically for signed-in customers.

The widget renders inside a shadow DOM at the highest z-index, so your site's CSS can't restyle or bury it — and the widget's styles never leak into your page.

The widget key identifies your widget to the loader script — it's the data-widget-key value baked into every snippet on the Deploy tab. It's public by design (it ships in your page source), and it's the same key the widget API uses.

Allowed domains

You can restrict which sites the widget accepts messages from by setting a domain allowlist on the widget. With domains listed, browser requests from any other domain are refused; entries match the exact host and its subdomains, and can be written as bare hosts (example.com), full URLs, or wildcards (*.example.com). With no domains listed, the widget works anywhere it's embedded. The allowlist is managed through the widget API.

Next steps

Widget customization — name, colors, theme, launcher, conversation starters, languages, and behavior.
Chat Page — the same chat as a hosted link, no install required.
AI agent → Deploy — turn AI answers on or off for the widget.

← Previous

Overview

Widget customization