Widget Embedding

Embedding a NodeLoom widget on your website requires a single script tag. The widget is a self-contained JavaScript bundle that automatically handles styling, real-time connections, and session management with no additional dependencies.

Getting the Embed Code

The embed code for each widget is available in the NodeLoom dashboard. Navigate to Settings → Widgets, select your widget, and click the Embed tab. Copy the provided script tag and paste it into your website's HTML.

Widget embed code

<!-- NodeLoom Chat Widget -->
<script
  src="https://your-instance.nodeloom.io/widget/embed.js"
  data-widget-token="your-widget-token"
  async>
</script>

Place the script tag just before the closing </body> tag for optimal page load performance. The async attribute ensures the widget loads without blocking your page content.

Works everywhere

The embed code works on any website regardless of framework or CMS -- static HTML, WordPress, Shopify, React, Vue, Angular, or any other platform that supports custom script tags.

Self-Contained Bundle

The widget embed script is a fully self-contained JavaScript bundle. It includes everything needed to render and operate the chat widget:

UI components: The complete chat interface including header, message list, input field, and toggle button.
Styles: All CSS is bundled inline and injected into a shadow DOM or scoped container to avoid conflicts with your page styles.
Real-time client: The messaging layer for streaming AI responses.
Session management: Visitor identification and conversation persistence.

There are no external CSS files to link, no additional JavaScript libraries to install, and no build step required. The single script tag is all you need.

Visitor Sessions

The widget automatically creates a persistent session for each visitor. Sessions are stored in the browser's local storage, so returning visitors see their previous conversation history when they reopen the widget.

Feature	Behavior
Persistent sessions	Conversations are tied to a visitor identifier stored in localStorage. Clearing browser data starts a new session.
Optional email collection	Enable the email collection prompt to identify visitors. The email is associated with the session and available in workflow data.
Conversation history	Previous messages are loaded when the widget is reopened. History is fetched from the server, not just local cache.

Privacy considerations

Visitor sessions use a randomly generated identifier by default -- no personally identifiable information is collected unless you explicitly enable email collection. See your privacy policy requirements before enabling visitor identification.

Real-Time Streaming

AI agent responses are streamed to the widget in real time. Visitors see tokens appear as they are generated, providing a responsive chat experience without waiting for the complete response.

The real-time connection is established when the widget is first opened and maintained for the duration of the session. If the connection drops, the widget automatically reconnects and resumes the conversation.

Streaming flow

Visitor sends message
  → Delivered to NodeLoom backend
    → Workflow executes AI Agent node
      → LLM generates tokens
        → Tokens streamed back to widget
          → Widget renders tokens in real time

Sensible Defaults

The widget works with minimal configuration. Out of the box, you get:

Default	Value
Position	Bottom-right corner
Theme	Light mode (adapts to system preference)
Welcome message	"Hi! How can I help you today?"
Input placeholder	"Type a message..."
Max message length	4,000 characters
Session persistence	Enabled
Email collection	Disabled
Streaming	Enabled

All defaults can be overridden through the dashboard configuration. The goal is to get a working widget with just the embed code and a connected workflow -- customization can come later.

Quick start

To get a widget live on your site in under two minutes: create a widget in the dashboard, connect it to a workflow with an AI Agent node, copy the embed code, and paste it into your HTML. Everything else uses sensible defaults.

Customization

Security