@inferedge/founding-agent-embed

Drop the Moss founding-agent voice bubble into any website. No framework required.

Install

npm install @inferedge/founding-agent-embed

import { init } from "@inferedge/founding-agent-embed";

init({ publishableKey: "pk_your_key" });

That mounts a fixed bubble in the corner. It works with any bundler (Vite, webpack, esbuild) and in any framework, or none.

Squarespace, Wix, WordPress and other no-build sites

Paste this into the site's footer code injection (on Squarespace: Settings, Advanced, Code Injection, Footer):

<script src="https://cdn.jsdelivr.net/npm/@inferedge/founding-agent-embed@1/dist/moss.js" data-moss-pk="pk_your_key"></script>

Then, in the Moss portal, add the site's exact host names, including the www. variant, to the agent's allowed domains -- the config endpoint matches hosts exactly. Once both are in place, the widget auto-initializes from the data-moss-pk attribute; no further setup is needed.

@1 tracks the latest 1.x release; to pin an exact version instead, use e.g. @1.2.0.

Auto-init from a data attribute

If you would rather not write the init call, the bundle mounts itself on any script tag carrying a publishable key:

<script type="module" src="/path/to/your/bundled/moss.js" data-moss-pk="pk_your_key"></script>

Optional attributes: data-moss-position="inline" with a data-moss-target="#selector", data-moss-color, data-moss-hide-on="#footer", data-moss-id.

Self-hosting the bundle

npm pack (or your bundler's output) gives you dist/moss.js (IIFE, exposes the MossFoundingAgent global) and dist/moss.mjs (ESM). Serve either from your own origin and the no-build forms work:

<script src="/assets/moss.js"></script>
<script>
  const widget = MossFoundingAgent.init({ publishableKey: "pk_your_key" });
  widget.on("connect", () => console.log("connected"));
</script>

<script type="module">
  import { init } from "/assets/moss.mjs";
  init({ publishableKey: "pk_your_key" });
</script>

Moss-hosted CDN: not available yet

A Moss-hosted build at https://cdn.moss.dev/founding-agent/... (an immutable /<version>/ path plus a moving /v<major>/ alias) is the intended zero-build install and is specified in SHIP-DESIGN.md. It is not serving yet -- the R2 bucket and its custom domain do not exist, so do not point production at those URLs. jsDelivr, which mirrors npm, is the supported hosted URL today (see "Squarespace, Wix, WordPress and other no-build sites" above); until Moss's own CDN ships, install from npm or self-host the bundle as above.

The release workflow (.github/workflows/js-founding-agent-embed-release.yml) already publishes to npm and will upload and promote the CDN paths once R2_BUCKET is configured; it skips those steps with a warning while it is not.

Configuration

init(options) returns a widget instance. Options:

| Option | Type | Default | Description | | --- | --- | --- | --- | | publishableKey | string | required | Your pk_... key from the portal. | | serviceUrl | string | Moss default | Backend service base URL. | | position | "fixed" \| "inline" | "fixed" | Bubble placement. | | target | string | none | CSS selector for inline mount. | | color | string | "violet" | Bubble color: a preset name (violet, cobalt, teal, emerald, coral, amber) or a #RGB/#RRGGBB hex. Ignored once the agent has a portal-configured appearance. | | themeMode | "light" \| "dark" | follows portal | Chrome + aura theme. Omitted = the portal appearance's widget_theme when configured, else light. | | appearance | object | fetched from portal | Explicit { shape, colors, soften, noise, widget_theme } override. Normally leave unset: the widget fetches the appearance saved in the portal and applies it automatically. | | label | string | none | Accessible bubble label. | | hideOnSelector | string | none | Hide the bubble while a matching element is in view. | | id | string | auto | Stable id for destroy(id). | | onNavigate | function | none | Called when the agent routes the page. |

The widget never writes into the host page's markup: agent navigation targets come from data-voice-section annotations and elements that already have an id.

Typed chat and intake form

The live pill has a chat toggle ("Show chat") that opens a panel above it with the recent turns and a text input: typing a message and pressing Enter sends it over lk.chat just like a spoken turn, and it is disabled while the intake form is open. The panel is closed by default and closes when the call ends. No host-site code change is needed to enable it.

If the agent has an intake form configured in the portal, a modal dialog opens after the agent's configured number of answers, pauses the mic while it is open, and posts the responses to the public intake endpoint on submit. The mic is restored whether the visitor submits or dismisses the form, and the form never reopens again for the rest of that session. Intake is opt-in per agent and is set up entirely in the portal, no init option required.

Instance methods and events

Methods: open(), end(), setMuted(bool), destroy(). Events via on(name, cb) / off(name, cb): connect, disconnect, error, transcript, bookingComplete, handoff. Global: MossFoundingAgent.init(...), MossFoundingAgent.destroy(id), MossFoundingAgent.destroyAll().

Getting a key

Create a founding agent in the Moss portal, then add your site's domain to the agent's allowed domains before the publishable key will work from that origin.

Subresource Integrity

If you serve the bundle from a URL you do not control, pin it with integrity. An SRI hash only matches one exact file, so always point it at an immutable path -- never at a moving major alias, which changes on every release and would break the hash. This includes the jsDelivr @1 tag used above: it moves to a new file on every 1.x release, so it cannot carry an integrity attribute -- pin an exact version such as @1.2.0 if SRI is required:

<script src="/assets/moss-1.2.0.js" integrity="sha384-..." crossorigin="anonymous"></script>

Generate the hash from the file you are serving:

openssl dgst -sha384 -binary dist/moss.js | openssl base64 -A