Mana Agent Embed Widget

Standalone embeddable chat widget (Bubble/Box style) that customers add to their site with a single custom element and script tag. Uses a 1st-party cookie for visitor identity and talks to the public embed chat API.

Embed on your site

Add this to your HTML (replace the agent ID and script URL with your values):

<myagent-webcomponent agent-id="<replace-with-your-agent-id>"></myagent-webcomponent>
<script
  src="https://unpkg.com/@builtbundle/ai-widget-embed"
  async
  type="text/javascript"
></script>

The bundle injects its own styles inside Shadow DOM, so no extra CSS file is required.

Attributes

• agent-id (required): Your agent ID from the dashboard.
• api-base-url (optional): Backend base URL (e.g. https://api.yourdomain.com). If omitted, the script uses the build-time env VITE_EMBED_API_URL.

By default, the widget calls ${base}/api/chat/embed/... (it auto-appends /api if missing).

Build-time API URL (hidden from embed HTML)

Set VITE_EMBED_API_URL when building so host pages do not need to expose API URL in the element attribute:

VITE_EMBED_API_URL=https://api.yourdomain.com pnpm build:embed

You can still override per embed instance with api-base-url if needed.

Cookie (1st-party)

The widget uses js-cookie to set a 1st-party cookie mana_visitor_id on the customer’s domain. This ID is sent as the X-Mana-Visitor-Id header to your server so conversations are tied to the same visitor.

Public embed API (server)

The server must expose these public (no auth) endpoints, rate-limited and identified by X-Mana-Visitor-Id:

• GET /chat/embed/conversation?agentId=... — get latest open conversation for this visitor.
• POST /chat/embed/conversation?agentId=... — create a new conversation (and optional welcome message).
• POST /chat/embed/conversation/:conversationId/messages — send a message (body: { "content": "..." }).
• POST /chat/embed/conversation/:conversationId/stop — archive (stop) the conversation.

Optional:

• GET /chat/embed/agent/:agentId — public agent config (name, image, spotlightMessages) for the widget.

All embed routes use publicRateLimitMiddleware and require the X-Mana-Visitor-Id header (the widget sends it from the cookie).

Local development

pnpm install
pnpm dev          # App with widget demo (main.tsx + App)
pnpm build:embed  # Build dist/ai-widget-embed.js

• Dev: Open the app and use the demo; set VITE_EMBED_API_URL to your API (e.g. http://localhost:4000).
• Build: After pnpm build:embed, serve dist/ and open an HTML page that includes the script and <myagent-webcomponent agent-id="…" api-base-url="http://localhost:4000" />.

Publish to unpkg (npm)

1. Authenticate npm:

npm login

2. Build and inspect package contents:

pnpm build:embed
npm pack --dry-run

3. Publish publicly (scoped package):

npm publish --access public

4. Use a pinned unpkg URL in production:

<script src="https://unpkg.com/@builtbundle/[email protected]"></script>

Notes:

• package.json already sets unpkg to dist/ai-widget-embed.js.
• prepublishOnly automatically runs pnpm build:embed before publish.
• Bump version for every release before publishing.

Tech

• Widget: Vite + React 19, Motion, TanStack Query, Axios, js-cookie, Tailwind, use-stick-to-bottom.
• Output: IIFE bundle (ai-widget-embed.js) for unpkg or self-host.
• Isolation: Web component runs in open Shadow DOM; host wrapper is fixed full-screen with pointer-events: none; only bubble/panel controls are pointer-events: auto so the embed does not block the site.