Skip to main content
Embedding Webchat v3 with a hosted script lets you integrate a Webchat widget interface into your website. By connecting the widget to your Cognigy.AI Endpoint and configuring the widget’s appearance and behavior, you can offer users seamless interaction and support without a complex setup. The script can be hosted remotely, for example, on GitHub, or on your own server.

​
Prerequisites

  • Ability to modify the HTML content of your website.
  • Access to a Cognigy.AI instance with the Webchat v3 Endpoint.
  • Familiarity with Webchat v3 embedding parameters. Keep in mind that:
    • Specifying parameters in the embedding code overwrites parameters configured in the Endpoint settings.
    • Some settings are specific to embedding parameters and aren’t available in the Endpoint settings.

​
Embedding

Copy the HTML code from the Webchat v3 Endpoint associated with your AI Agent, which you want to deploy on your website:
  1. In the left-side menu of the Project, go to Deploy > Endpoints.
  2. On the Endpoints page, select a Webchat v3 Endpoint that you recently created.
  3. In the Endpoint settings, go to the Embedding HTML section.
  4. Copy the HTML code by hovering over the code editor and clicking the Copy to clipboard button.
  5. The HTML code contains the following entities:
    • The Webchat JavaScript bundle — hosted externally on GitHub, ensures that your web page loads the latest version of Webchat v3. You can also deploy another Webchat v3 version by replacing https://github.com/Cognigy/Webchat/releases/latest/download/webchat.js with https://github.com/Cognigy/Webchat/releases/download/<webchat-version>/webchat.js, where <webchat-version> is the Webchat v3 version you want to use. For example, to use Webchat v3.2.0, enter https://github.com/Cognigy/Webchat/releases/download/v3.2.0/webchat.js. If you enter a specific version, ensure it is the same or later than the version where the Webchat v3 features you use were introduced. Learn more about Webchat v3 versions on the Webchat v3 release page.
    • The initWebchat() function — initializes the Cognigy Webchat widget with the provided configuration. The initWebchat() function is called with the required argument, which is the Config URL of the Webchat v3 Endpoint to connect to. This file contains the necessary JavaScript code to initialize and display the Cognigy Webchat widget on the web page.
    <script src="https://github.com/Cognigy/Webchat/releases/latest/download/webchat.js"></script>
<script>
    initWebchat(
        "https://endpoint-trial.cognigy.ai/c62364a8a1b1e986efc5c5b3bed5b2300aeab6788a6551f88fa24dcf9c37dbmf"
    );
</script>

​
Include Custom Plugins and Stylesheets

If you have custom plugins or stylesheets for the webchat, 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:
  • colors — customize a Webchat v3 color. In the example:
    • primaryColor — change the primary color.
  • behavior — customize the Webchat v3 behavior by adjusting Webchat v3 Endpoint settings. In the example:
    • enableTypingIndicator — activate a typing indicator to show when the AI Agent is replying.
    • messageDelay — set the time interval, in milliseconds, between AI Agent’s messages.
    • enableSTT — enable the speech-to-text button in the Reply section of the chat. Note that Mozilla Firefox doesn’t support this parameter.
  • embeddingConfiguration — activate settings related to Webchat browser embedding. These settings aren’t configurable via the Endpoint Editor.
    • awaitEndpointConfig — wait for the loading of the endpoint configuration. This setting is a necessary precondition for the maintenance settings.
  • maintenance — configure maintenance mode to prevent users from using Webchat during maintenance. In the example:
    • mode — informing the user about maintenance mode. Choose to either hide the Webchat widget, disable it or inform the user about maintenance mode.
    • text — a text displayed to users during maintenance mode. For example: The agent is currently in maintenance mode, please try again later.
    • title — a title displayed to the user during maintenance mode if the mode is set to inform. For example, Maintenance Hours. Leave empty for no header.
  • customAllowedHtmlTags — set a custom array of HTML tags that are allowed in Webchat widget messages. By default, Webchat allows a wide range of HTML tags. The array you set in this parameter overrides the default setting. If you need to restrict the allowed HTML tags for security reasons, use this parameter to include only the allowed HTML tags.
Example: 
<script>
  initWebchat('https://endpoint-trial.cognigy.ai/URLTOKEN', {
    settings: {
      colors: {
        primaryColor: "#fab",
      },
      behavior: {
        enableTypingIndicator: true,
        messageDelay: 5,
        enableSTT: true,
      },
      embeddingConfiguration: {
        awaitEndpointConfig: true,
      },
      maintenance: {
        enabled: true,
        mode: "inform",
        text: "The agent is currently in maintenance mode, try again later",
        title: "Maintenance hours",
      },
      widgetSettings: {
        customAllowedHtmlTags: [
          "a", "abbr", "acronym", "address", "applet", "area", "article", "aside", "audio",
          "b", "base", "basefont", "bdi", "bdo", "big", "blockquote", "body", "br", "button",
          "canvas", "caption", "center", "cite", "code", "col", "colgroup", "data", "datalist",
          "dd", "del", "details", "dfn", "dialog", "dir", "div", "dl", "dt", "em", "embed",
          "fieldset", "figcaption", "figure", "font", "footer", "form", "frame", "frameset",
          "h1", "h2", "h3", "h4", "h5", "h6", "head", "header", "hr", "html", "i", "img",
          "input", "ins", "kbd", "label", "legend", "li", "link", "main", "map", "mark", "meta",
          "meter", "nav", "noframes", "object", "ol", "optgroup", "option", "output", "p",
          "param", "picture", "pre", "progress", "q", "rp", "rt", "ruby", "s", "samp", "section",
          "select", "small", "source", "span", "strike", "strong", "style", "sub", "summary",
          "sup", "svg", "table", "tbody", "td", "template", "textarea", "tfoot", "th", "thead",
          "time", "title", "tr", "track", "tt", "u", "ul", "var", "video", "wbr"
        ]
      },
    }
  });
</script>

​
RTL Configuration

By default, the Webchat widget uses the LTR (left-to-right) layout. To override this setting for languages that use RTL (right-to-left), add the attribute dir="rtl" to the <html> tag on the web page where the widget is placed. For example, for a web page in Arabic, use <html lang="ar" dir="rtl">.

​
Test your Webchat

After implementing the code, open your web page in a browser to test the functionality.
  • LTR (Left-to-Right) Layout
  • RTL (Right-to-Left) Layout
<html lang="en">
<body>
<script src="https://github.com/Cognigy/Webchat/releases/latest/download/webchat.js"></script>
<script src="./path/to/myPlugin.js"></script>
<link rel="stylesheet" href="./path/to/myStylesheet.css"/>
<script>
    initWebchat('https://endpoint-trial.cognigy.ai/URLTOKEN', {
      settings: {
        colors: {
          primaryColor: "#fab",
        },
        behavior: {
          enableTypingIndicator: true,
          messageDelay: 5,
          enableSTT: true,
        },
        embeddingConfiguration: {
          awaitEndpointConfig: true,
        },
        maintenance: {
          enabled: true,
          mode: "inform",
          text: "The agent is currently in maintenance mode, try again later",
          title: "Maintenance hours",
        },
      },
    }
    );
  </script>
</body>
</html>

​
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 to match the design language of your website.
  • 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.
⌘I