API REFERENCE

The Widget API

The widget as an API. Drop in one script tag, then configure it with data-* attributes, pass the signed-in user through window.ERAConfig, and drive it from your own code with window.ERA.

The widget is a vanilla JavaScript bundle with zero dependencies that renders inside a Shadow DOM, so it never collides with your styles. You embed it with a single script tag. Everything past that is optional: attributes on the tag for look and behavior, a global config object for who the user is, and a small JS API for opening it, sending messages, and listening to the stream.

The embed snippet

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

html

<script
  src="https://eerraa.online/static/widget.js"
  data-api-key="era_your_project_key"
  data-title="Assistant"
  data-primary-color="#19c37d"
  data-placeholder="Ask me anything..."
  data-position="bottom-right"
></script>

data-* attributes

Configure the widget declaratively on the script tag.

Field	Type	Description
`data-api-key`required	string	Your project key, era_.... Identifies the project and gates allowed origins.
`data-primary-color`	string	Accent color for the launcher and buttons. Defaults to #19c37d.
`data-title`	string	Header title shown at the top of the panel.
`data-placeholder`	string	Placeholder text in the message input.
`data-position`	"bottom-right" \| "bottom-left"	Which corner the launcher sits in. Defaults to bottom-right.
`data-theme`	"dark" \| "light"	Force a color scheme instead of following the host page.
`data-max-length`	number	Maximum characters a user may type in one message.
`data-feedback`	"off"	Set to "off" to hide the thumbs up / thumbs down feedback controls.
`data-options`	"off"	Set to "off" to disable the clickable choice buttons the agent can render.
`data-status-style`	"professional" \| "playful"	Tone of the live tool-status labels while the agent works.
`data-base-url`	string	Point the widget at your own proxy instead of eerraa.online, for example to keep the project key server-side.

window.ERAConfig (who the user is)

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.

html

<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>

Field	Type	Description
`user.id`required	string	Stable identifier for the end user. Scopes sessions, private knowledge, credentials, and tasks.
`user.name`	string	Display name, available to the agent.
`user.email`	string	User's email, available to the agent.
`user.role`	string	Your own role label, usable in policies.
`user.data`	object	Arbitrary key/values the agent can read and that policies match on (user.data.*).
`user._ts`	number	Signed mode: Unix seconds when the identity was signed. Valid for 300 seconds.
`user._sig`	string	Signed mode: HMAC-SHA256 over the canonical identity. Produced server-side, never in a public env var.

Never compute _sig in the browser. The signing secret is server-side only. See the signed identity guide for the exact canonicalization.

window.ERA (JavaScript API)

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

Field	Type	Description
`ERA.open()`	function	Open the chat panel.
`ERA.close()`	function	Close the chat panel.
`ERA.sendMessage(text)`	function	Send a message as the user, as if they typed it. Opens the panel if closed.
`ERA.clear()`	function	Clear the current conversation and start a fresh session.
`ERA.onMessage(fn)`	function	Register a callback that fires as the agent streams. See the payload below.
`ERA.openTasks()`	function	Open the My-tasks panel (signed mode).
`ERA.connectMcp(serverId)`	function	Start the per-user MCP OAuth flow for a server, from your own button.

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.

Field	Type	Description
`type`	string	Event kind, for example "text", "tool_start", "tool_end", or "done".
`content`	string	For text events, the incremental chunk of the reply.
`full`	string	The reply so far, already concatenated for you.
`name`	string	For tool events, the tool being called.

javascript

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 === "done") {
    console.log("reply complete");
  }
});

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

Write actions still pause for Approve or Cancel inside the widget, and the Stop button always cancels an in-flight reply. Driving the widget with ERA does not bypass those confirmations.

PREVIOUSMCP OAuth API NEXTError Reference