The Widget API

Paste this once, near the end of your page body. Only data-api-key is required.

<script
  src="https://agentifys.ai/static/widget.js"
  data-api-key="era_your_project_key"
  data-title="Assistant"
  data-primary-color="#6366f1"
  data-placeholder="Ask me anything..."
  data-position="bottom-right"
></script>

Configure the widget declaratively on the script tag. Every attribute is read once, when the script runs; changing one afterwards has no effect on the live widget.

Set this global before the script loads to tell the widget who is signed in. The id is required; the rest personalizes the agent and feeds policies through data. In signed mode you also attach a _ts and _sig, which unlock private uploads, the vault, per-user MCP OAuth, and the My-tasks panel.

<script>
  window.ERAConfig = {
    user: {
      id: "u_42",
      name: "Sara Arabiat",
      email: "sara@example.com",
      role: "admin",
      data: { plan: "pro", region: "MENA" },
      // signed mode only, produced server-side:
      _ts: 1735689600,
      _sig: "a1b2c3..."
    }
  };
</script>

When the widget reads it

The widget does not snapshot ERAConfig at boot. It reads window.ERAConfig.user fresh at the moment it makes a request — every POST /v1/chat, every private upload, every scheduled-task and MCP OAuth call. Replacing the object hands a running widget a new identity; there is nothing to reload and no re-injection needed.

Two things are read only once, while the script is running:

• The console warning when no user.id is set.
• The GET /v1/project-config feature gate below, which is skipped entirely if window.ERAConfig.user.id is absent at that moment. Set ERAConfig before the widget tag. Setting it later still personalizes messages, but the attach button, the My-tasks footer and the Connect prompts stay hidden until the script is injected again.

Keeping a signature fresh

A _sig is valid for 300 seconds after its _ts. On a page that stays open longer than that — a dashboard, an admin console, anything a user leaves in a tab — one signature obtained at page load will expire underneath them. Because the identity is re-read per request, the fix is to re-sign on a timer and assign the result:

// Your endpoint returns the signed context ({ id, name, ..., _ts, _sig }).
async function refreshEraIdentity() {
  const signed = await fetch("/api/era-identity").then((r) => r.json());
  window.ERAConfig = { user: signed };   // the next widget request uses this
}

refreshEraIdentity();
setInterval(refreshEraIdentity, 240000);   // 240s, comfortably inside the 300s window

This is the first request the widget makes, before it loads any history. It asks the server which optional affordances this project is allowed to show. It is a public endpoint: the project key goes in the query string, there is no Authorization header and no origin check, so anyone holding the key can read it. Keep nothing sensitive in the project name or tagline.

curl "https://agentifys.ai/v1/project-config?api_key=era_your_project_key"

Response:

{
  "name": "Acme Support",
  "tagline": "",
  "logo_color": "#6366f1",
  "identity_mode": "signed",
  "kb_uploads_enabled": true,
  "scheduling_enabled": true,
  "mcp_oauth_connect_enabled": true,
  "mcp_oauth_servers": [
    { "server_id": "srv_7a21", "label": "Google Drive" }
  ]
}

Once the script has loaded, window.ERA lets you drive the widget from your own code.

The ERA.onMessage(fn) callback receives an event object as the agent works. Use it to mirror the conversation elsewhere, drive UI, or react to tool activity. It is a single global slot rather than a subscription: registering again replaces the previous callback, and there is no unsubscribe other than passing null.

ERA.onMessage((e) => {
  if (e.type === "text") {
    console.log("so far:", e.full);
  } else if (e.type === "tool_start") {
    console.log("calling tool:", e.name);
  } else if (e.type === "error") {
    console.log("stream error:", e.content);
  } else if (e.type === "done") {
    console.log("final reply:", e.full);
  }
});

// Kick off a conversation from your own button:
document.querySelector("#help").addEventListener("click", () => {
  ERA.sendMessage("How do I reset my API key?");
});

Instead of describing where a button is, the agent can put a ring on the real thing. It opts in by ending its reply with a fenced era-ui block. The widget parses the block out, runs it, and never renders it as text — the same explicit-contract approach as the quick-reply choices block.

It is in Settings, here:

```era-ui
{"action":"point","target":"invite","label":"Invite a teammate"}
```

Two things to set up on your side, and the agent knows the block format already:

1. Mark the elements you want reachable with data-era-id, for example <button data-era-id="invite-teammate">. Prefer this over CSS selectors, which break the next time you restyle.
2. Tell the agent those ids exist. Add a section headed exactly Screen elements you can point at to your project's system prompt, listing each id and what it does. The agent is instructed to use only ids from that section, so until you add it nothing is highlighted and replies simply describe the path in words.

## Screen elements you can point at
- invite-teammate — the Invite button on Settings, Team
- api-keys — the API keys panel on Settings, Developers
- billing-plan — the plan selector on Billing

The widget renders in an open Shadow DOM and exposes a supported theming surface, so you can re-skin it to your brand without editing the widget or overriding its internal classes. Two building blocks: a set of --era-* CSS custom properties for colors and radii, and ::part() handles for styling specific elements. Prefer these over targeting internal ids, which can change between widget versions.

CSS variables

Parts (::part hooks)

How to apply it

Method A — set the variables on the widget host element from your page CSS. Custom properties inherit through the open shadow boundary, so this re-themes everything that reads them:

#era-widget {
  --era-accent: #7c3aed;
  --era-panel: #0b0b12;
  --era-surface: #171722;
  --era-radius-bubble: 20px;
}

Method B — inject a stylesheet into the open shadow root. Use this for ::part() rules or when you need a guaranteed override:

const w = document.getElementById("era-widget");
const s = document.createElement("style");
s.textContent = `
  :host { --era-accent: #7c3aed; }
  ::part(panel) { box-shadow: 0 12px 40px rgba(0,0,0,.35); }
  ::part(send)  { border-radius: 12px; }
`;
w.shadowRoot.appendChild(s);

Try it

Adjust the controls and copy the generated CSS. The preview mirrors how the widget reads these variables.

/* Put the same colour on the script tag — data-primary-color="#2F6FED" —
   because the widget bakes those channels into its glows at boot. */
#era-widget {
  --era-accent: #2F6FED;
  --era-accent-rgb: 47,111,237;
  --era-panel: #18181b;
  --era-surface: #27272a;
  --era-text: #e4e4e7;
  --era-radius-bubble: 18px;
}