> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayerup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedding the Chat Widget

> Add a fully managed support chat widget to any website or mobile app with a single script tag.

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.

```html theme={null}
<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.

<Note>
  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.
</Note>

***

## Multiple widget instances

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.

```html theme={null}
<!-- 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>
```

***

## Triggering the widget from your own code

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.

```js theme={null}
// Open the chat programmatically
window.__layerupWidget?.open();

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

<Warning>
  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.
</Warning>

**Example — custom button trigger:**

```html theme={null}
<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.

<Tabs>
  <Tab title="iOS (Swift)">
    ```swift theme={null}
    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)
    ```
  </Tab>

  <Tab title="Android (Kotlin)">
    ```kotlin theme={null}
    val webView = WebView(context)
    webView.settings.javaScriptEnabled = true
    webView.loadUrl("https://us.uselayerup.com/widget/YOUR_WIDGET_ID")
    ```
  </Tab>

  <Tab title="React Native">
    ```jsx theme={null}
    import { WebView } from 'react-native-webview';

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

For authenticated sessions in a webview, append the identity params to the URL — see [Identity Verification](/integrations/chat-widget/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:

```js theme={null}
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;
```