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

# Webchat 3: Embedding via npm

[Updated in 2026.10](https://docs-classic.cognigy.com/release-notes/2026.10.md)

Embedding Webchat v3 using npm lets you add a Webchat widget to your JavaScript project. This approach works best for modern web apps that use npm packages and bundlers.

The [Webchat npm](https://www.npmjs.com/package/@cognigy/webchat) package lets you pin versions and integrate Webchat into CI/CD pipelines, giving your team better control and stability across environments.

## Prerequisites

* Basic understanding of JavaScript and npm. Familiarity with how to run a JavaScript project, for example, using `npm start` or similar commands.
* A JavaScript project set up with npm and the ability to modify it.
* Access to a Cognigy instance with the [Webchat v3 Endpoint](https://docs-classic.cognigy.com/webchat/v3/configuration.md).
* Familiarity with Webchat v3 [embedding parameters](https://github.com/Cognigy/Webchat/blob/main/docs/embedding.md). Keep in mind that:
  * Specifying parameters in the embedding code overwrites parameters configured in the Endpoint settings.
  * Some settings are [specific to embedding parameters](https://github.com/Cognigy/Webchat/blob/main/docs/embedding.md#embedding-configuration) and aren't available in the Endpoint settings.

## Restrictions

* The minimum supported React version is 18.

## Embedding

To embed Webchat v3 in your JavaScript project, follow these steps:

1. Install the Webchat npm package:

   ```bash theme={null}
   npm install @cognigy/webchat
   ```

2. Import and initialize the Webchat widget in your JavaScript code:

   > [tab] ESM (requires React)
   >
   > When using the ESM build in a non-React project, you need to include React and ReactDOM manually (React 18 or 19):
   >
   > ```html theme={null}
   > <!-- Include React and ReactDOM (React 18 or 19) -->
   > <script src="https://unpkg.com/react@18/umd/react.development.js"></script>
   > <script src="https://unpkg.com/react-dom@18/umd/react-dom.development.js"></script>
   >
   > <!-- Include Webchat ESM bundle via bundler (for example, Webpack, Rollup) -->
   > <script type="module">
   >   import { initWebchat } from "@cognigy/webchat";
   >
   >   initWebchat("https://endpoint-trial.cognigy.ai/c62364a8a1b1e986efc5c5b3bed5b2300aeab6788a6551f88fa24dcf9c37dbmf");
   > </script>
   > ```

   > [tab] UMD (includes React)
   >
   > The UMD build is self-contained and can be used directly without including React or ReactDOM:
   >
   > ```html theme={null}
   > <!-- Include Webchat UMD bundle directly -->
   > <script src="https://unpkg.com/@cognigy/webchat/dist/webchat.umd.js"></script>
   >
   > <script>
   >     initWebchat("https://endpoint-trial.cognigy.ai/c62364a8a1b1e986efc5c5b3bed5b2300aeab6788a6551f88fa24dcf9c37dbmf");
   > </script>
   > ```
   >
   > The `initWebchat()` function is called with the required argument, which is the Config URL of the Webchat v3 Endpoint to connect to.

## Include Custom Plugins and Stylesheets

If you have custom [plugins](https://docs-classic.cognigy.com/webchat/plugins.md) or [stylesheets](https://github.com/Cognigy/Webchat/blob/main/docs/css-customization.md):

```js theme={null}
import "./path/to/myPlugin.js";
import "./path/to/myStylesheet.css";
```

## Customize Webchat Settings

You can customize the widget using a configuration object passed to `initWebchat`:

```js theme={null}
initWebchat('https://endpoint-trial.cognigy.ai/URLTOKEN', {
  settings: {
    colors: {
      primaryColor: "#fab",
    },
    behavior: {
      enableTypingIndicator: true,
      messageDelay: 5,
      enableSTT: true, // Note: Not supported in Firefox
    },
    embeddingConfiguration: {
      awaitEndpointConfig: true,
    },
    maintenance: {
      enabled: true,
      mode: "inform", // hide | disable | inform
      text: "The agent is currently in maintenance mode, try again later",
      title: "Maintenance hours",
    },
    widgetSettings: {
      customAllowedHtmlTags: ["a", "abbr", "address", "article", "b", "blockquote", "div", "span", "img", "p"], // Example
    },
  },
});
```

## RTL (Right-to-Left) Configuration

For RTL languages, ensure the HTML root element has the `dir="rtl"` attribute:

```html theme={null}
<html lang="ar" dir="rtl"></html>
```

The Webchat widget will automatically adjust its layout.

## Test Webchat

Run your JavaScript project and verify the widget loads and interacts correctly.

## What's Next?

Customize Webchat further to align with your brand identity and meet specific interaction goals:

* [Webchat API](https://github.com/Cognigy/Webchat/blob/main/docs/webchat-api.md). Use the Webchat API to create tightly coupled integrations.
* [CSS Customization](https://github.com/Cognigy/Webchat/blob/main/docs/css-customization.md). Customize the look and feel of the Webchat to match the design language of your website.
* [Analytics API](https://github.com/Cognigy/Webchat/blob/main/docs/analytics-api.md). Get notified and react to events that happen in your Webchat.
* [Custom Avatars](https://github.com/Cognigy/Webchat/blob/main/docs/custom-avatars.md). Change the avatar of the bot or user during the conversation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.