Embedding the Chat Widget

The Layerup chat widget runs inside a sandboxed <iframe> served from Layerup’s infrastructure. You embed it with a script tag and it self-renders a floating bubble in the bottom-right corner. No build step, no npm package — it works on any page.

Prerequisites

Before embedding, go to your company’s Integrations page in the Layerup dashboard and create or open your Chat Widget integration. Inside that integration you manage your widget instances (one per brand, product, or colour scheme). Each instance has its own embed key — a UUID that you pass to the script tag.

Basic embed

Copy the snippet from the dashboard for the widget instance you want to embed, and paste it before the closing </body> tag on any page.

<script
  src="https://us.uselayerup.com/widget-loader.js"
  data-widget-key="YOUR_WIDGET_ID">
</script>

That’s it. The script creates a chat bubble and a hidden iframe. When a user clicks the bubble, the chat opens.

Replace YOUR_WIDGET_ID with the UUID shown in the dashboard for the specific widget instance. Each widget instance has a different ID — don’t mix them up.

If you have more than one product or brand, create a separate widget instance for each in the dashboard. Each gets its own ID and colour scheme. Embed them on different pages using the corresponding ID — there’s no other configuration required.

<!-- Widget for Product A -->
<script
  src="https://us.uselayerup.com/widget-loader.js"
  data-widget-key="WIDGET_ID_A">
</script>

<!-- Widget for Product B -->
<script
  src="https://us.uselayerup.com/widget-loader.js"
  data-widget-key="WIDGET_ID_B">
</script>

After the script loads it exposes window.__layerupWidget with two methods: open() and close(). This lets you trigger the widget from any button or workflow in your own code instead of using the default floating bubble.

// Open the chat programmatically
window.__layerupWidget?.open();

// Close it
window.__layerupWidget?.close();

The __layerupWidget object is only available after the script has loaded. Wait for the script’s onload event or check for its existence before calling it.

Example — custom button trigger:

<button onclick="window.__layerupWidget?.open()">Contact support</button>

<script
  src="https://us.uselayerup.com/widget-loader.js"
  data-widget-key="YOUR_WIDGET_ID">
</script>

Mobile webview

On mobile apps, instead of embedding the script, load the widget URL directly in a native WebView:

https://us.uselayerup.com/widget/YOUR_WIDGET_ID

This renders the full chat UI without the floating bubble shell. All features (session history, file attachments, authenticated identity) work the same way.

iOS (Swift)
Android (Kotlin)
React Native

let url = URL(string: "https://us.uselayerup.com/widget/YOUR_WIDGET_ID")!
let webView = WKWebView(frame: view.bounds)
webView.load(URLRequest(url: url))
view.addSubview(webView)

val webView = WebView(context)
webView.settings.javaScriptEnabled = true
webView.loadUrl("https://us.uselayerup.com/widget/YOUR_WIDGET_ID")

import { WebView } from 'react-native-webview';

<WebView
  source={{ uri: 'https://us.uselayerup.com/widget/YOUR_WIDGET_ID' }}
/>

For authenticated sessions in a webview, append the identity params to the URL — see Identity Verification.

Cleanup

If you inject the script dynamically and need to remove the widget later (e.g. on a single-page app route change), call the cleanup function and remove the script element:

window.__layerupWidgetCleanup?.();
document.querySelector('script[data-layerup-init]')?.remove();
delete window.__layerupWidget;

Content Security Policy

If your site uses a strict CSP, add the following directives:

frame-src https://us.uselayerup.com;
script-src https://us.uselayerup.com;
connect-src https://us.uselayerup.com;

Chat Widget

Embedding the Chat Widget

Prerequisites

Basic embed

Multiple widget instances

Triggering the widget from your own code

Mobile webview

Cleanup

Content Security Policy

​Prerequisites

​Basic embed

​Multiple widget instances

​Triggering the widget from your own code

​Mobile webview

​Cleanup

​Content Security Policy

Prerequisites

Basic embed

Multiple widget instances

Triggering the widget from your own code

Mobile webview

Cleanup

Content Security Policy