Install the widget

One script tag. No build step, no package to install, no framework integration.

The snippet

<script
  src="https://widget.minaya.ai/widget.js"
  data-site-key="your-site-key"
  data-api-url="https://api.minaya.ai"
  async
></script>

Copy the version with your real site key from Install & embed in the dashboard. Place it before the closing </body> tag.

Attributes

Attribute	Required	Purpose
`src`	Yes	Where the script is served from (a CDN).
`data-site-key`	Yes	Identifies your business. Public, but only works on allowlisted domains.
`data-api-url`	Yes	Your Minaya backend. Separate from `src` — the script and the API can live on different hosts.
`async`	Recommended	Keeps the script from blocking page render.

data-api-url must point at your API, not the CDN serving the script. Pointing it at the CDN produces 403 on every request, because that host has no API.

Framework notes

Next.js

import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://widget.minaya.ai/widget.js"
          data-site-key="your-site-key"
          data-api-url="https://api.minaya.ai"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

WordPress

Paste the snippet into your theme's footer template, or use a “header and footer scripts” plugin. Adding it to a child theme keeps it through updates.

Shopify

Add it to theme.liquid just before </body>.

Single-page apps

The widget mounts once and persists across client-side navigation. Do not mount it per-route.

Page rules from the Pages setting follow client-side navigation too: the widget hides and reappears as the route changes, without a reload, and keeps the conversation.

Domain allowlist

The widget only works on origins you list in the dashboard. Include every host visitors use:

https://example.com
https://www.example.com
https://staging.example.com

Origins are matched exactly, so example.com and www.example.com are different entries.

Troubleshooting

Symptom	Cause
`403` on requests	Origin not allowlisted, or `data-api-url` points at the CDN.
Nothing appears	Script did not load, or `data-site-key` is missing. Check the console.
Wrong colours	Config is cached briefly; hard-reload after saving changes.
Widget behind other elements	Raise its `z-index` via Custom CSS.
A red message in the chat saying it isn’t configured correctly	The site key doesn’t match any widget (copy it again from Embed), or this domain isn’t in the widget’s allowed origins. The console names which.
A red message saying the chat can’t reach Minaya	`data-api-url` is wrong, or the API is unreachable from the visitor’s browser. The message shows the URL it tried.
Nothing on some pages only	A Pages rule hides it there — see Placement and behaviour.

Rotating your site key

Rotating invalidates the old key immediately and every existing embed stops working, so update your snippet in the same change.

PreviousCustom CSS NextFrameworks & platforms