Skip to content

Webchat 2: Embedding


Starting from version 4.77, the 18-month countdown to the deprecation of Webchat v2 begins. During this time, only important security updates will be provided for v2, with no further feature additions.

Embedding Webchat v2 into your website allows you to provide a conversational interface powered by virtual agents, enhancing user interaction and support. This process involves several key steps, from setting up your Cognigy Endpoint to configuring the widget's appearance and behavior on your website.


  • Ability to modify the HTML content of your website.
  • Familiarity with Webchat v2 embedding parameters. Note that specifying parameters in the embedding code that are already configured in Endpoint Settings will overwrite them.
  • Create a Webchat Endpoint.

Add the Embedding HTML

Copy the HTML code from the Webchat v2 Endpoint associated with your virtual agent, which you want to deploy on your website:

  1. Open the Cognigy.AI interface.
  2. In the left-side menu, select an Agent.
  3. In the left-side Agent menu, select Deploy > Endpoints.
  4. On the Endpoints page, select a Webchat Endpoint that you recently created.
  5. On the Endpoint Settings page, go to the Embedding HTML section.
  6. Copy the HTML code by hovering over the code editor and clicking the Copy to clipboard button.
  7. The HTML code contains the following entities:

    • The Webchat JavaScript bundle. This bundle, hosted externally on GitHub, ensures that your webpage loads the latest version of Webchat v2.
    • The initWebchat() function. This function initializes the Cognigy Webchat widget with the provided configuration. The initWebchat() function is called with a single argument, which is the Config URL of the Webchat v2 Endpoint to connect to. This file contains the necessary JavaScript code to initialize and display the Cognigy Webchat widget on the webpage.
    <script src=""></script>

Include Custom Plugins and Stylesheets

If you have custom plugins or stylesheets for the Webchat widget, include them by adding the appropriate <script> and <link> tags respectively. Replace the placeholders with the paths to your custom files.

<script src="./path/to/myPlugin.js"></script>
<link rel="stylesheet" href="./path/to/myStylesheet.css"/>

Customize the Webchat Settings

You can customize the Webchat settings according to your requirements:

  • userId โ€” assign a unique ID to each user.
  • sessionId โ€” assign a session ID for the current chat session.
  • settings โ€” customize the Webchat v2 behavior by changing the Webchat Endpoint settings. In the example:
    • disableLocalStorage โ€” disable local storage of chat history.
    • useSessionStorage โ€” determine whether to use session storage.


    initWebchat('', {
        userId: "user2",
        sessionId: "session2",
        settings: {
            disableLocalStorage: true,
            useSessionStorage: false
    }).then(function (webchat) {
        window.cognigyWebchat = webchat;


When embedding the code, if you're using the maintenance, businessHours, and connectivity settings, ensure that you include the [awaitEndpointConfig]( setting. Otherwise, those settings won't function.

Test Your Webchat

After implementing the code, open your webpage in a browser to test the functionality.

<html lang="en">
    <script src=""></script>
    <script src="./path/to/myPlugin.js"></script>
    <link rel="stylesheet" href="./path/to/myStylesheet.css"/>
        initWebchat('', {
            userId: "user2",
            sessionId: "session2",
            // Set endpoint settings
            settings:{"disableLocalStorage": true, "useSessionStorage": false}
        }).then(function (webchat) {
            window.cognigyWebchat = webchat;
            // send message:
            // open Webchat Widget

What's Next?

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

  • Webchat API. Use the Webchat API to create tightly coupled integrations.
  • CSS Customization. Customize the look and feel of the Webchat widget to match the design language of your website.
  • Persistent History. Learn how to save user's chat history, so they can refer to them later.
  • Analytics API. Get notified and react to events that happen in your Webchat.
  • Custom Avatars. Change the avatar of the bot or user during the conversation.