Embed & Integration

The Simple Agent widget is a 5-line <script> tag that works on any site — plain HTML, React, Vue, WordPress, Webflow, Framer, or any other CMS.

Standard snippet

<script
  src="https://simple-agent.me/widget/loader.js"
  data-agent-id="YOUR-AGENT-ID"
  async
></script>

Paste this snippet before </body> on every page where you want the widget.

---

Available parameters

Attribute	Type	Default	Description
data-agent-id	string	—	Required. Your agent ID
data-position	string	bottom-right	Position: bottom-right, bottom-left
data-color	string	Extracted from site	Hex color for the bubble button
data-open	boolean	false	Opens the chat automatically
data-hide-branding	boolean	false	Removes "Powered by Simple Agent" (Growth+ plan)
data-allowed-paths	string	*	Regex of paths where the widget appears
data-locale	string	Auto-detect	en, pt-BR, es

Example with all parameters

<script
  src="https://simple-agent.me/widget/loader.js"
  data-agent-id="ag_xxxxxxxxxxx"
  data-position="bottom-left"
  data-color="#a3e635"
  data-hide-branding="true"
  data-allowed-paths="/products/.*|/checkout"
  data-locale="en"
  async
></script>

---

React / Next.js

In React, add the script via useEffect or using Next.js's Script component:

// With Next.js Script component (recommended)
import Script from "next/script";

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <>
      {children}
      <Script
        src="https://simple-agent.me/widget/loader.js"
        data-agent-id={process.env.NEXT_PUBLIC_AGENT_ID}
        strategy="lazyOnload"
      />
    </>
  );
}

// Plain React with useEffect
import { useEffect } from "react";

function App() {
  useEffect(() => {
    const script = document.createElement("script");
    script.src = "https://simple-agent.me/widget/loader.js";
    script.setAttribute("data-agent-id", "YOUR-AGENT-ID");
    script.async = true;
    document.body.appendChild(script);
  }, []);

  return <div>...</div>;
}

---

WordPress

1. Go to Appearance → Theme Editor (or use a script plugin such as Header and Footer Scripts)
2. Paste the snippet before the </body> tag in footer.php
3. Save — the widget appears on all pages

Recommended plugin: Insert Headers and Footers — adds scripts without editing theme files.

---

Webflow

1. Go to Project Settings → Custom Code
2. Paste the snippet in the Footer Code section
3. Publish the project

---

Per-page control (conditional)

Use data-allowed-paths to show the widget only on specific pages:

<!-- Only on cart and checkout -->
<script
  src="https://simple-agent.me/widget/loader.js"
  data-agent-id="YOUR-AGENT-ID"
  data-allowed-paths="/cart|/checkout.*"
  async
></script>

The value is a regex applied to window.location.pathname.

---

JavaScript API (programmatic)

After the widget loads, you can control it via API:

// Open the chat
window.Simple Agent.open();

// Close the chat
window.Simple Agent.close();

// Send a pre-defined message
window.Simple Agent.send("I want to know about the Agency plan");

// Listen for a new message event
window.Simple Agent.on("message", (msg) => {
  console.log("New message:", msg.content);
});

---

Multiple agents on the same site

You can have different agents per section:

<!-- Support agent in the footer -->
<div id="agent-support"></div>
<script>
  window.Simple AgentConfig = {
    containerId: "agent-support",
    agentId: "ag_support_xxx",
    mode: "inline", // inline doesn't create a bubble
  };
</script>
<script src="https://simple-agent.me/widget/loader.js" async></script>

---

Security and CORS

The widget uses RS256 JWT for authentication. Add your authorized domains in the agent panel under Security → Allowed domains.

Requests from unauthorized domains receive HTTP 403 before any LLM call.

For details on JWT signing, see API Reference.