live-layerdocs
View as markdown

Script tag overview

The fastest way to put an agent on any site that lets you paste HTML — WordPress, Webflow, Shopify, Squarespace, plain HTML, even a Notion page that allows embeds.

Quickstart

  1. Publish your agent

    In the dashboard, open the agent and click Publish. Copy the agent ID (e.g., agt_abc123).

  2. Paste two lines into your HTML

    Drop these anywhere in your page (typically right before </body>):

    html
    <script src="https://livelayer.app/v1.js"></script>
<livelayer-widget agent-id="agt_abc123"></livelayer-widget>

  3. Done

    The widget appears as a floating bubble in the bottom-right. Visitors click it to start a conversation.

How it works

v1.js is the bundled @livelayer/sdk widget. It registers a <livelayer-widget> custom element. When the browser sees that element, it:

  1. Reads attributes (agent-id, mode, etc.)
  2. Fetches the published agent config from livelayer.app
  3. Mounts a Shadow-DOM-isolated UI (your styles can't leak in, ours can't leak out)
  4. Wires the LiveKit session, mic permission, video track, transcript

Because it's a custom element, it works in any HTML environment — frameworks, plain pages, CMSes, even inside another shadow root.

What's bundled

v1.js is a single ~150 KB gzipped file containing:

  • livekit-client (the WebRTC layer)
  • The <livelayer-widget> custom element
  • LiveKitSession (session lifecycle)
  • The capability-gated agent command runner (navigate / scroll / click)

Nothing else loads from your origin — all session state lives at livelayer.app.

Configuration via attributes

The widget reads HTML attributes for configuration. The most common:

html
<livelayer-widget
  agent-id="agt_abc123"
  mode="widget"
  position="bottom-right"
  capabilities="navigate,scroll,click">
</livelayer-widget>

See Attributes for the full list.

What you can do from here

  • Pick a mode (floating bubble vs inline embed vs fullscreen) → Modes
  • Restrict what the agent can do on your page → Capabilities
  • React to lifecycle events (opened, conversation started, ended) → Events
  • Track visitors automatically (page views, clicks, scroll depth) → Visitor tracking

When to graduate to NPM

The script tag handles 90% of marketing-site use cases. Reach for NPM when:

  • Your app is React-based and you want the agent to access component state
  • You need the agent to fill or submit forms in your app
  • You need the agent to read text from your visible DOM (not just navigate)
  • You need a fully custom UI — your own avatar dock, your own controls
  • You need an SSO/auth-aware session (your server mints tokens)