Embedding Options

Multiple ways to embed the Monology chat widget on your website.

Overview

Monology provides flexible embedding options to fit any tech stack. Choose the method that works best for your website—from simple script tags to full React integration.

⚠️ Important CSS Warning

The host site should not have CSS directly applied to semantic HTML elements like p, a, ul, li, h1-h6, etc.

Why? Global CSS rules on these elements will conflict with the Widget's internal styles and disturb its appearance.

Solution: Use CSS classes or scoped styles instead of element selectors. For example, use .my-paragraph instead of p in your stylesheets.

Vanilla JavaScript

The simplest way to add the widget to any website. Just add the script tag and initialize with your widget ID.

Without Identity Verification

Basic setup for anonymous users. The widget handles everything automatically.

<!-- Add before closing </body> tag -->
<script src="https://your-subdomain.monology.io/chat-widget.js"></script>
<script>
  const widget = initMonologyWidget({
    containerId: 'your-widget-url-id',
    urlId: 'your-widget-url-id'
  });
</script>

With Identity Verification

Pass user information when you already have authenticated users on your site.

<script src="https://your-subdomain.monology.io/chat-widget.js"></script>
<script>
  const widget = initMonologyWidget({
    containerId: 'your-widget-url-id',
    urlId: 'your-widget-url-id',
    identity: {
      id: '1234567890',
      firstName: 'John',
      lastName: 'Doe',
      email: 'john.doe@example.com',
      phone: '1234567890',
      company: {
        name: 'Acme Inc',
        id: '1234567890'
      }
    }
  });
</script>

React / Next.js Package

For React applications, use our official npm package. Supports both TypeScript and JavaScript.

Installation

npm install @monology-io/chat-widget
# or
yarn add @monology-io/chat-widget
# or
pnpm add @monology-io/chat-widget

Next.js (CSR Component)

For Next.js App Router, use dynamic import with SSR disabled.

"use client";
import dynamic from "next/dynamic";
const RenderWidget = dynamic(
  () => import("@monology-io/chat-widget").then((mod) => mod.RenderWidget),
  { ssr: false }
);

export default function App() {
  return (
    <div className="App">
      <RenderWidget urlId='your-widget-url-id' identity={null} />
    </div>
  );
}

React (No Manual Control)

Basic usage with the default launcher button.

import { RenderWidget } from "@monology-io/chat-widget";

export default function App() {
  return (
    <div className="App">
      <RenderWidget urlId='your-widget-url-id' identity={null} />
    </div>
  );
}

React (Manual Control)

Control the widget open/close state with your own button.

import { RenderWidget } from "@monology-io/chat-widget";
import { useState } from "react";

export default function App() {
  const [isWidgetOpen, setIsWidgetOpen] = useState(false);
  return (
    <div className="App">
      <button onClick={() => { setIsWidgetOpen(true) }}>Open Widget</button>
      {isWidgetOpen && (
        <RenderWidget
          urlId='your-widget-url-id'
          onClose={() => { setIsWidgetOpen(false) }}
          hideLauncherButton={true}
          identity={null}
        />
      )}
    </div>
  );
}

React (With Identity)

Pass user identity for SaaS applications with authenticated users.

import { RenderWidget } from "@monology-io/chat-widget";

export default function App() {
  return (
    <div className="App">
      <RenderWidget 
        urlId='your-widget-url-id' 
        identity={{
          firstName: "John",
          lastName: "Doe",
          email: "john.doe@example.com",
          phone: "1234567890",
          id: "1234567890",
          company: {
            id: "1234567890",
            name: "Acme Inc",
          }
        }} 
      />
    </div>
  );
}

Props Reference

Prop	Type	Description
widgetId	string	Required. Your widget ID from the dashboard.
user	object	Optional. User identity object with email, name, customData.
showLauncher	boolean	Show/hide the default launcher button. Default: true.
defaultOpen	boolean	Open the widget on initial load. Default: false.
onMessage	function	Callback fired when messages are sent/received.

Best Practices

1
Load asynchronously
Place the script at the end of the body to avoid blocking page load.
2
Pass user data when available
If users are logged in, pass their info to skip verification and enable tracking.
3
Test on staging first
Verify the widget works correctly before deploying to production.

Next Steps

Share Chat Link

Generate shareable URLs for your chatbot