Widget Installation

Copy the generated installation code from your Agent’s Deploy page. It includes both the Agent ID and the widget API key.

HTML and static websites

Add the script before the closing </body> tag in the shared layout used by the pages where you want chat:


<script
  src="https://widget.loopreply.com/loader.js"
  data-agent-id="your-agent-id"
  data-api-key="your-widget-api-key"
  defer
></script>

Use the values from Deploy. The widget key is intended for this browser installation. Do not substitute a server credential, an AI provider key, or a workspace administrative credential.

Install the loader once. It loads the full widget bundle and initializes the Agent. You do not need a second embed.js script.

Next.js

Use next/script in the shared layout. This example loads the widget after the main page resources:


import Script from 'next/script'
 
export function ChatWidget() {
  return (
    <Script
      id="loopreply-widget"
      src="https://widget.loopreply.com/loader.js"
      data-agent-id="your-agent-id"
      data-api-key="your-widget-api-key"
      strategy="lazyOnload"
    />
  )
}

Render ChatWidget once in your site’s root layout rather than separately on every client-side route.

React and other single-page applications

The simplest option is the HTML script in your app’s document template. If your application needs to add it in code, initialize it once in a component that remains mounted for the lifetime of the app:


import { useEffect } from 'react'
 
export function ChatWidget() {
  useEffect(() => {
    if (document.getElementById('loopreply-widget-loader')) return
    const script = document.createElement('script')
    script.id = 'loopreply-widget-loader'
    script.src = 'https://widget.loopreply.com/loader.js'
    script.dataset.agentId = 'your-agent-id'
    script.dataset.apiKey = 'your-widget-api-key'
    script.async = true
    document.body.appendChild(script)
  }, [])
 
  return null
}

Removing the loader script does not destroy an initialized widget. Keep this component in the app shell and avoid inserting a new loader on every navigation.

Website builders and commerce platforms

For WordPress, Shopify, Wix, Squarespace, or Webflow, use the platform’s supported custom-code or footer-code setting. Add the complete script from Deploy and publish the website. Access to custom scripts can depend on your website plan and permissions.

Test on the published site. A website editor or preview frame can have a different domain or block third-party scripts.

Verify configuration and domain access

Before testing:

Save and publish your Agent’s workflow and appearance changes.
Confirm the Agent is active and the website channel is enabled.
Copy the current Agent ID and widget key from Deploy.
If allowed domains are configured, include your public website domain.
Open the website and check that the launcher, conversation, and expected answers work.

Knowledge uploads must finish processing before they can support answers. Supported sources explains that distinction.

Troubleshooting

No launcher appears

Check for a paused Agent, an incorrect Agent ID or widget key, domain restrictions, blocked network requests, and browser extensions. Inspect the browser console and network panel for the actual error.

Test the Agent in the dashboard, inspect workflow configuration, and confirm attached knowledge sources are ready. Check the usage allowance in Workspace settings and any error returned by the API.

The public design differs from the preview

The preview can use a saved draft. Publish the intended changes and reload the public website to check the visitor configuration.

See Widget customization and Events and callbacks for the next steps.

Last updated on October 9, 2026