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 the site's published state, 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. Publish the site that owns it.
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.

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

Only data-agent is required. Do not put a MAF API key, provider key, connector token, visitor identity, or private customer data in any data-* attribute.

Configure attributes#

Without a theme override, 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.

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 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, or a website builder, choose the matching guide in the sidebar. Platforms that do not allow arbitrary JavaScript, such as many Notion and Linktree surfaces, should link to the published hosted agent instead.