Embed overview

How the embed works#

embed.js adds one fixed launcher to the host document. The visitor's first click reveals a lazy-loaded iframe from https://makeagent.fast; the agent and conversation remain isolated from the host page inside that frame. Host CSS cannot restyle the chat, and agent content cannot rewrite the host document.

The loader is public and does not use an API key. Access is controlled by its Enable embedding switch and the exact parent-origin allowlist. The site slug is an identifier, not a secret.

Prerequisites#

Before copying code:

1. Create and test an agent in the dashboard.
2. Use the agent’s generated snippet; publishing its separate public page is not required.
3. Open the site's Embed page and turn Enable embedding on.
4. Add every parent origin that will render the launcher.
5. Save, then copy the generated snippet.

An origin contains only the scheme, hostname, and optional port. It never contains a path. These are four different origins and must be added separately when you use them:

https://example.com
https://www.example.com
https://staging.example.com
http://localhost:3000

Do not enter https://example.com/pricing, *.example.com, or a trailing wildcard. If production redirects from the bare domain to www, allowlist the origin that remains in the browser address bar after the redirect.

Install the loader#

Place one script before the closing </body> tag, or use the browser-only lifecycle recommended by your framework guide.

The dashboard Embed page copies this shape (site slug, position, optional label, and the ?v= cache-buster). Keep async. Keep the ?v= query from the snippet so hosts do not pin a stale loader.

<script
  src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  async
></script>

Only data-agent is required. Optional attributes the loader actually reads:

<script
  src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  data-label="Ask us"
  data-accent="#6d5ce7"
  data-locale="en"
  data-theme="light"
  async
></script>

Do not put a MAF API key, provider key, connector token, visitor identity, or private customer data in any data-* attribute. Do not invent attributes such as data-api-key, data-z-index, data-offset, or data-delay. data-maf-bootstrapped is set by the loader.

Configure attributes#

Read from the embed.js tag only. The iframe accepts hex accents only.

Without data-theme, the loader samples the host background and then falls back to the visitor's OS preference. It also passes the host font family to the frame and fetches the latest launcher appearance. A failed appearance request does not block the launcher; it keeps the safe default style. Look saves in the dashboard refresh this fetch without a site republish.

Runtime behavior#

• Load the script once per document. Repeating the same slug is idempotent and still produces one maf-embed-root-YOUR_SITE_SLUG root.
• Different agents may coexist on one document. The loader marks each processed script with data-maf-bootstrapped so an async fallback initializes every distinct data-agent tag exactly once.
• The iframe is lazy and hidden until the visitor opens it. It requests microphone, autoplay, and clipboard-write permission only through the browser's iframe permission model.
• In a client-side routed app, mount the loader in the highest layout that should own it so route changes do not reload the conversation.
• Removing only the script element does not remove an already-created launcher. For route-specific teardown, also remove the matching maf-embed-root-... element. Reload the script after teardown to mount it again.
• The frame and loader exchange only namespaced lifecycle messages. The loader rejects messages that do not come from the Make Agent Fast origin and current site slug.

Verify the installation#

Test the public page, not only a website-builder editor preview:

1. Open the deployed URL in a private window and confirm its exact origin is allowlisted.
2. Confirm https://makeagent.fast/embed.js?v=20260728-widget-v2 returns 200 in the Network panel.
3. Confirm a single element with data-maf-embed="YOUR_SITE_SLUG" exists.
4. Open the launcher and confirm the iframe request to /embed/YOUR_SITE_SLUG succeeds.
5. Send a realistic question and confirm it appears in Conversations.
6. Test a narrow mobile viewport and, if enabled, microphone permission.

Diagnose a missing launcher#

Choose an installation guide#

Use HTML and JavaScript for a normal script tag. For React, Vue, SvelteKit, Astro, WordPress, Shopify, Webflow, Framer, Wix, Squarespace, or Ghost, choose the matching guide in the sidebar. Platforms that do not allow arbitrary JavaScript, such as many Notion and Linktree surfaces, can link to the agent’s enabled Public page, available in the final onboarding step and agent settings. A customer website with the embed is another option.

For coding agents#

Installing this on a customer site with Claude Code, Cursor, or Codex? Copy skills/embed-agent/SKILL.md from the Make Agent Fast repository into .cursor/skills/embed-agent/ or .claude/skills/embed-agent/. That file is the install recipe (attributes, CSP, placement). This page remains the human guide.