ashh.ai
Start free

Docs

Embed reference

Last updated: May 5, 2026

The Ashh.ai widget is a single <script> tag you paste into any webpage. By default it reads its appearance from your bot's dashboard config — but you can override theme, position, colors, and placement on a per-installation basis using data-* attributes on the script tag, or via a window.ashhConfig global before the script loads.

Build your snippet visually in the bot's detail page — the snippet builder there has a live preview iframe so you can see exactly what visitors will experience before you copy the code.

Three placement modes

1. Floating bubble (default)

<script src="https://ashh.ai/api/embed/YOUR-BOT-SLUG.js" defer></script>

Appears as a chat bubble in the bottom corner. Visitor clicks to open the panel. Header has expand-to-larger and pop-out-to-tab buttons.

2. Inline panel

<div id="ashh-chat" style="height: 600px; max-width: 800px; margin: 0 auto;"></div>

<script src="https://ashh.ai/api/embed/YOUR-BOT-SLUG.js"
        data-position="inline"
        data-mount="#ashh-chat"
        defer></script>

Mounts the chat panel directly inside a specific element on your page — no bubble, panel always open. Useful for help-center pages, marketing demos, or any page where the bot is the headline feature.

3. Standalone link

<a href="https://ashh.ai/chat/YOUR-BOT-SLUG" target="_blank">Chat with us</a>

Opens a dedicated full-page chat in a new tab. Conversations persist across navigation if the visitor came from an embedded widget on the same domain (the ?session=... param is forwarded automatically by the “pop-out” button on the floating panel).

data-* attribute reference

Add any of these to the <script> tag to override the bot's defaults for this installation:

data-theme

Values: dark, light, auto. Forces a color scheme regardless of the visitor's system preference.

data-position

Values: bottom-right, bottom-left, inline. The corner the bubble docks to, or inline for inline mode (requires data-mount).

data-mount

Required when data-position="inline". CSS selector for the target element where the chat panel will mount. Example: #ashh-chat or .support-chat-container. The widget logs a console warning and falls back to floating mode if the selector matches no element.

data-primary & data-accent

6-character hex colors with leading #. Override the bot's primary and accent (gradient) colors for this site only. Validated server-side; invalid values silently fall back to the bot default.

data-bubble

Values: circle, rounded, square, animated. The shape of the floating bubble.

animated floats the bot's logo (set in the dashboard) at 72×72px with a gentle bob + pulsing glow halo. Tuned for product pages that want a more attention-grabbing widget than the default chat-icon circle.

data-greeting

Set to false to suppress the greeting popup on this site, even if the bot has one configured.

data-suggestions

Set to false to hide quick-reply chips below the welcome message on this site.

data-open

Set to true to auto-open the chat panel when the page loads. Useful for kiosk-mode deployments where the chat is the primary feature of the page.

data-z-index

Numeric. Override the widget's z-index if it conflicts with another floating element on your site (modals, sticky headers, video players).

Full example with overrides

<script src="https://ashh.ai/api/embed/YOUR-BOT-SLUG.js"
        data-theme="light"
        data-position="bottom-left"
        data-primary="#FF5722"
        data-accent="#FFC107"
        data-bubble="square"
        data-greeting="false"
        data-z-index="99999"
        defer></script>

window.ashhConfig (advanced)

For programmatic control, set a config object on window before the script loads. Same options as data-*:

<script>
  window.ashhConfig = {
    theme: "light",
    position: "bottom-left",
    primary: "#FF5722",
    open: true,
    greeting: false
  };
</script>
<script src="https://ashh.ai/api/embed/YOUR-BOT-SLUG.js" defer></script>

window.Ashh.mount() / window.Ashh.unmount()

For React, Vue, Svelte and other SPA frameworks where the mount target appears and disappears with route changes, use the imperative API instead of data-mount. Each call to mount() creates a fresh widget instance; unmount() tears it down cleanly.

Drop the embed script once in the page <head> (no data-mount) and then:

// React example — inline chat panel inside an /ask route
import { useEffect, useRef } from 'react';

export function AskPanel() {
  const ref = useRef<HTMLDivElement>(null);
  useEffect(() => {
    window.Ashh?.mount(ref.current);
    return () => window.Ashh?.unmount(ref.current);
  }, []);
  return <div ref={ref} style={{ minHeight: 480 }} />;
}

Multiple inline mounts on the same page are supported (e.g. one per tab or accordion). Each gets its own shadow-DOM panel and conversation session. Re-mounting into the same element is idempotent — the prior instance is torn down first.

Visitor capabilities

When enabled in the bot's dashboard config, visitors can:

  • Read replies aloud via Web Speech API — adds a 🔊 button below each assistant reply.
  • Speak instead of type via mic button — uses the browser's SpeechRecognition (Chrome / Edge / Safari).
  • Upload a document via the paperclip button or drag-and-drop — Ashh.ai runs OCR on our GPUs and the bot answers questions about that document. Visitor uploads are scoped to the conversation, not the bot's permanent knowledge base, and never used to train models.
  • Expand the panel from compact to a wider 720px view via the header button — preference persists in sessionStorage.
  • Pop out the conversation into a dedicated tab — the same conversation continues seamlessly, with prior messages hydrated from the server.

Rich response content

Bots configured with rich blocks enabled can render:

  • Inline videos — YouTube, Vimeo, and Loom URLs in responses auto-embed as iframe players.
  • Inline images and PDFs — image URLs render inline; PDF links become styled download chips.
  • Action buttons — owner-defined CTAs (Book a demo, View pricing, etc.) the bot suggests at the right moment.
  • Cards & carousels — product tiles with images, titles, descriptions, CTAs.
  • Tables — structured data renders as actual <table>, not flaky markdown.
  • Tool results — bots wired with custom HTTP tools (Anthropic-model bots) can fetch live data from your APIs and summarize the results.

What's NOT overridable per-installation

The bot's behavior stays consistent across all deployments. These are configured only in the dashboard:

  • System prompt & persona (use the prompt builder under the bot's Identity tab)
  • AI model
  • Knowledge base (uploaded documents, crawled sites, connected sources)
  • Action library (CTAs the bot can suggest)
  • Custom tools (function-calling endpoints)
  • Domain allowlist & rate limits
  • Welcome message text

This separation is intentional — visual presentation is yours to tweak per site, but the bot's knowledge and personality should stay coherent everywhere it appears.

Caching

The embed script is cached for 5 minutes by Caddy. After you change the bot's dashboard config, allow up to 5 min for the change to propagate to embedded sites (or hard-refresh the host page). data-* attribute changes apply instantly on the next page load — those don't go through the embed script.

CORS & security

The chat endpoint emits CORS headers per-request, reflecting the requesting Origin. Domain-scoped restrictions are configured per-bot via the Security tab — set an allowlist (e.g. your-site.com) and only those origins can chat. Subdomain matches are automatic.

Per-IP rate limiting is on by default (20 req/min). Adjustable per-bot in the Security tab. Backed by Redis sliding-window so it survives restarts.

Need help?

Email hi@ashh.ai or open the chat on this page.