While it can be easy to customize the Cognigy webchat with your own JavaScript code to expand the default functionality, the difficulty usually comes when wanting to persist these changes reliably.

Example:

You wish to add a new button in the header of the webchat to send the user to a separate website as a call-to-action.

What is the MutationObserver?

You can utilize the MutationObserver web API that is commonly available in most browsers to check for updates to the DOM and the execute code, like injecting new elements such as buttons.

The MutationObserver works by watching a specific part of the page for changes in the DOM, such as new elements being added or existing ones being modified. When the observer detects a change that matches the criteria you’ve set (like a new chat header being loaded), it triggers a callback function where you can run your custom logic — for example, injecting a new button. This allows your customizations to remain reliable even when the webchat content loads dynamically or updates after the initial page load, making MutationObserver a powerful tool for enhancing the webchat experience in real time.

All you need to do to implement this technical functionality would be to add the MutationObserver to the JavaScript of your website, such as in the location where you embed your webchat widget.

Sample code

A simple example of this setup in the HTML of your website would look like this:

<script src="https://github.com/Cognigy/Webchat/releases/latest/download/webchat.js"></script>
<script>
    initWebchat(
        "https://endpoint-trial.cognigy.ai/0b44e4XXXXXXXXXXXXXXXXXXXXXXXXXXX"
    );
    // Iterate for mutations
    let observer = new MutationObserver((mutations) => {
        mutations.forEach((mutation) => {
            if (!mutation.addedNodes) return;
        });
        // Check if header bar is found
        let headerbarSearchResults = document.getElementsByClassName("webchat-header-bar");
        if (headerbarSearchResults.length) {
            let headerbar = headerbarSearchResults.item(0);
            if (document.getElementById("plant-tree-button")) {
                // If custom button is already placed, do nothing
            } else {
                // If custom button can not be found, add button
                let plantTreeButton = document.createElement("button");
                plantTreeButton.id = "plant-tree-button";
                plantTreeButton.className = "plant-tree-button";
                plantTreeButton.ariaLabel = "Plant a tree";
                plantTreeButton.innerHTML = '<a href="https://www.acacia.com/plant-a-tree">Plant a tree</a>';
                headerbar.insertBefore(plantTreeButton, headerbar.childNodes[0]);
            }
        }
    });
    // Check for mutations
    observer.observe(document.body, {
        childList: true,
        subtree: true,
        attributes: false,
        characterData: false,
    });
</script>

Warning: Depending on the specificity of your mutation observer and the number of changes to the DOM happening on a regular basis, this can potentially crash you site by recursively causing too many changes to observe.

Scoping the MutationObserver

The above example shows a relatively wide-scoped mutation observer. Specifically, the observer observes the whole webpage (document) and starts observing as soon as the webchat is initialized. Scoping, or 'narrowing the job' of the observer reduces the chances that it will cause problems with existing webpage elements, such as when the page already contains many mutations.

Observe only the webchat in the DOM.

Here we see that we're observing the whole page body (document.body)

observer.observe(document.body, {});

We can be more specific, and only observe the webchat by selecting the root of the webchat widget:

observer.observe(document.querySelector('[data-cognigy-webchat-root="true"]'),{}); 

Start the observer only when the chat opens, stop it when the webchat closes

For this we can use the Cognigy Webchat Analytics API. We call observer.observe, only when we get the "webchat/open" event, and we disconnect the mutation observer on "webchat/close".

webchat.registerAnalyticsService((event) => {
  if (event.type === "webchat/open") {
    observer.observe(
      document.querySelector('[data-cognigy-webchat-root="true"]'),
      {
        attributes: true,
        childList: true,
        subtree: true,
        characterData: true,
      }
    );
  } else if (event.type === "webchat/close") {
    observer.disconnect();
  }
});

Using the above methods you can easily develop very custom functionalities that extend the scope of the out-of-the-box webchat widget without the need to create a custom fork of the open-source webchat.