Webchat 3: Embedding via npm - Cognigy Documentation

Embedding Webchat v3 using npm

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 package lets you pin versions and integrate Webchat into CI/CD pipelines, giving your team better control and stability across environments.

Prerequisites

Restrictions

Embedding

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

  1. Install the Webchat npm package:

    npm install @cognigy/webchat

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

    • ESM (requires React)
    • UMD (includes React)

When using the ESM build in a non-React project, you need to include React and ReactDOM manually (React 18 or 19):

   <!-- 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>

The UMD build is self-contained and can be used directly without including React or ReactDOM:

   <!-- 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 or stylesheets:

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:

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 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: