Integrate the legacy Webchat on your own website

Description

❗️

This Webchat is DEPRECATED

Please use Cognigy's 2.X webchat. Refer to Cognigy's new webchat documentation: Webchat

📘

Latest Version

The latest version of this LEGACY Webchat is 1.1.10.

You can easily deploy the COGNIGY.AI Webchat on your own webiste to bring Conversational AI directly your website visitors.

This How to covers the necessary steps to quickly integrate the Webchat into your own website and connect it to COGNIGY.AI. There are several ways to integrate the Webchat into your own Website, namely:

  • Automatic integration via a Webchat Endpoint
  • Manual integration via a Socket Endpoint.

Both of these options will be covered in this guide.

🚧

Webchat URL change

We changed the URL to the Webchat in release 3.0.6. The Webchat is now served from https://downloads.cognigy.com/CognigyWebchat//cognigyWebChat.js

Guide Structure

  1. Integrating the Webchat on your website via a Webchat Endpoint
  2. Integrating the Webchat on your website via a Socket Endpoint
  3. Webchat Configuration Options
  4. Persistent Menu
  5. Design Templates
  6. Versioning
  7. Webchat Releases
  8. Modifying the Webchat
  9. Output Callback
  10. Using the COGNIGY.AI Client to Send Messages

Background

There are only two components you need to know about when integrating the Webchat into your website. The first is the Webchat source code itself, which is a minified JS file that you can easily integrate into your project. We host all versions of the Webchat (e.g. the minified file) on one of our servers so that you can easily load it in your website. You can read more about this here: Versioning.

The second important component is the Cognigy object that is exposed when you integrate the Webchat source file into your HTML document. This object contains an init() function, which takes two parameters: A config object, and an optional callback function, that will be called on every Flow output. There are several ways to define the config object, depending on your specific use case, and you can read more about this in the following chapters.

As for the callback function, you can read more about that here.

Integrating the Webchat into your website with a Webchat Endpoint

Using a Webchat Endpoint when integrating the Webchat into your website has many benefits, most notably that you can use our Webchat Endpoint Builder in the COGNIGY.AI User Interface. This way, you can easily adjust the color of the Webchat, add a Persistent Menu and much more, without having to get a developer to change the Webchat deployment. As soon as you change the Webchat Endpoint, the changes will be available immediately on your website.

Creating the Webchat Endpoint


If you don't know what a Webchat Endpoint is, you can quickly read the guide here to understand everything you can configure in the Webchat Endpoint.

Otherwise, the first thing you have to do is to create a Webchat Endpoint. When you have done this, you can see two URLs: a Config URL and a Webchat URL. The Webchat URL points to a COGNIGY.AI deployment of the Webchat that you can use to easily showcase your Flows. The Config URL is what we need in this guide. The Config URL tells the Webchat where it can connect in order to load the configuration that you have created.

Figure: Webchat with Config URLFigure: Webchat with Config URL

Figure: Webchat with Config URL

Deploying the Webchat with the Config URL


The simplest way by far to deploy the Webchat is to just copy/paste the Config URL into the Cognigy.init function. By doing this, the Webchat will load the entire configuration that you have defined in the Webchat Endpoint and use that. This will therefore essentially be equal to the Webchat you see when you click the Open Webchat button.

<body>
  <script type="text/javascript" src="https://downloads.cognigy.com/CognigyWebchat/v1.1.10/cognigyWebChat.js"></script>

  <script>
    // Insert your own Config URL here
    Cognigy.init("https://endpoint-dev.cognigy.com/f22f3f35794fa49d6dd2449c3c38e1a9ed36b05a7d2388ab75e2ccac1f4ebbf9");
  </script>
</body>

Here the first script fetches the COGNIGY.AI Webchat files, as described previously. We then call the Cognigy.init function in order to load the Webchat - we only give it one parameter, which is the Config URL that you can find in you Webchat Endpoint. Simply open the HTML file in your browser, and you should see your Webchat. This is all it requires to integrate the COGNIGY.AI Webchat into your website.

Extending the configuration


There might be situations where you want to use the Config URL to be able to change the Webchat in the COGNIGY.AI User Interface, but where you want to make small modifications for your website. This can for instance be if you don't want to have the background image rendered on your website, or if you want to define a specific userId.

It is very easy to extend the Webchat Endpoint configuration for the Webchat deployed on your website. Instead of passing in the Config URL to the Cognigy.init function, you create a config object. This config object as a minimum needs to have the key configUrl whose value is the Config URL of the Webchat. You can then add any other configuration settings that the Webchat supports to the object.

<body>
  <script type="text/javascript" src="https://downloads.cognigy.com/CognigyWebchat/v1.1.10/cognigyWebChat.js"></script>

  <script>
    var configObject = {
      // Insert your own Config URL here
      configUrl: "https://endpoint-dev.cognigy.com/f22f3f35794fa49d6dd2449c3c38e1a9ed36b05a7d2388ab75e2ccac1f4ebbf9",
      backgroundImageUrl: null,
      userId: "[email protected]"
    };

    Cognigy.init(configObject);
  </script>
</body>

In the snippet above, we create a config object with the same configUrl as before. However, we have decided that we don't want to render a background image, so we set this value to null. This ensures that even though you have a background image url defined in your Webchat Endpoint, it will not get rendered on your website. We then also set a userId to avoid creating a random one.

Here you can read which options you can override in the config object.

👍

Setting a userId

It is highly recommended that you set a userId if you have a user who is logged in on your website. This ensures that the user will be the same across multiple sessions, and therefore have the correct contact profile.

If you don't set the userId, then we will create a random ID and set it in local storage to try to have the same userId across multiple visits.

Integrating the Webchat into your website with a Socket Endpoint

You can use a Socket Endpoint to integrate the Webchat into your website if you want to have as much of the configuration locally. When you choose this option, you have to configure the Webchat by using a config object to define colors etc, and you therefore cannot use our Webchat builder in our COGNIGY.AI User Interface.

The first thing you have to do is to create a Socket Endpoint by following the guide in Endpoints . The Endpoint is used by the Webchat to know which Flow is should connect to and so on. You need to use the Endpoint URL and the URLToken of the endpoint when setting up the Webhchat.

Figure: Creating a Socket EndpointFigure: Creating a Socket Endpoint

Figure: Creating a Socket Endpoint

Afterwards, you can integrate the COGNIGY.AI Webchat into your website by adding the following two scripts into the body of your HTML:

<script type="text/javascript" src="https://downloads.cognigy.com/CognigyWebchat/v1.1.10/cognigyWebChat.js"></script>
<script>
    const options = {
        "baseUrl": "https://endpoint-dev.cognigy.com",
        "URLToken": "9e96fbbb0b133b71bd390226d26b1511d53446e3da59c38d56ce274d046f1fe1",
        "userId": "[email protected]",
        "sessionId": "GDZEAc8DRdCt4xeerEeZ3KjeAY8j",
        "designTemplate": 2,
        "colorScheme": "#3D6FBD",
        "persistentMenu": {
            "title": "Menu",
            "menuItems": [
                {
                    "title": "Help",
                    "payload": "Help"
                }
            ]
        },
        "getStartedText": "Hello",
        "getStartedPayload": "Hello"
    };

    Cognigy.init(options);
</script>

The first snippet loads a specific version of the COGNIGY.AI Webchat, while the second snippet initializes the COGNIGY.AI Webchat based on your options.

Webchat Configuration Options

The following table shows all the options you can pass into the Cognigy.init() function.

Name

Type

Default

Required

Description

baseUrl

string

Yes

This is the Endpoint URL that points to the Socket Endpoint that you created.

URLToken

string

Yes

This is the URLToken for the Socket Endpoint that you created.

userId

string

Random initialized userId or value from local storage.

The username of the user that connects. We initialize the user randomly per default and store the user in localStorage, but you should use a username to have access to the context on multiple visits.

sessionId

string

Random va

The ID of the current session. This should be a unique identifier that is regenerated when a user starts a new conversation. We generate a random ID per default.

displayGetStartedButton

boolean

true

Whether to display a Get Started Button when loading the Webchat.

getStartedText

string

"Get Started"

The text to display in the Webchat when clicking the Get Started Button.

getStartedPayload

string

"GET_STARTED"

The payload to send to your Flow when clicking the Get Started Button.

getStartedButtonText

string

"GET_STARTED"

The text to display on the Get Started Button.

inputPlaceholder

string

"Write a reply"

The placeholder text to display in the input field.

enableFileUpload

boolean

false

Whether to display a button that handles file uploads when clicked.

enableSTT

boolean

false

Whether to enable a microphone button that lets the user speak to the Webchat instead of only typing.

enableTTS

boolean

false

Whether to enable the browser to read the bot messages aloud.

colorScheme

string

"#333333"

The background color of the header and bot messages in the Webchat.

designTemplate

number

1

The Webchat design template to use. We default to design template 1. Go here for more info.

messageLogoUrl

string

COGNIGY.AI Logo

The logo to display next to the messages from your bot in the Webchat. Defaults to a COGNIGY.AI logo.

headerLogoUrl

string

COGNIGY.AI Logo

The logo to display in the header of the Webchat. Defaults to a COGNIGY.AI logo.

backgroundImageUrl

string

No default value

If defined, then we will render the specified image as the background of the page.

enableTypingIndicator

boolean

true

Whether to enable typing indicators in the Webchat when the Conversational AI is replying. Requires a messageDelay to be set.

messageDelay

number

2000

The amount of milliseconds to wait before sending each reply from the Conversational AI. This is also the amount of time the typing indicators will be shown if enabled.

NOTE
This value has to be set in the Endpoint Configuration in the UI. It cannot be set in the options object when initializing the Webchat.

enablePersistentMenu

boolean

false

Whether to enable the Persistent Menu

persistentMenu

JSON

None

The Persistent Menu to render in the Webchat.

Persistent Menu

The persistent menu is a great way to show your users all of the capabilites that your bot has. You can use it to switch to different conversation stages, to guide the user and much more. The user can open the menu at any time during the conversation through a small icon in the left corner:

Figure: Persistent MenuFigure: Persistent Menu

Figure: Persistent Menu

An example of how to create the persistentMenu is below. The title is the title of the menu ("Menu", "Bots" etc.), and the "menuItems" is a list of all the menuItems you need to help your user. We recommend not putting too much information here as it might confuse more than it helps. Each menuItem has a title, which is what the user sees, and a payload, which is what is sent to your flow.

{
  "persistentMenu": {
    "title": "Menu",
    "menuItems": [
        {
          "title": "Help",
          "payload": "Help"
        },
        {
          "title": "Find Restaurants",
          "payload": "Find restaurants near me"
        },
        {
          "title": "Get Recommendations",
          "payload": "Get recommendations for places to eat"
        }
    ]
  }
}

Design Templates

Here at COGNIGY.AI, we focus a lot on building conversations, but we are not limited to only building your dialogues - we want to build entire conversational experiences that range from the inner workings of the chatbot to the integration on your website. That is why we have built these design templates that let you experience how you can make conversations a natural and integrated part of your websites. We currently only have two design templates, but there are many more to come.

Design Template 1


Our first (and default) design template is the standard website chat that you often see in the lower right corner of websites:

Figure: Design Template 1Figure: Design Template 1

Figure: Design Template 1

Design Template 2


Our second design template looks like the first, however it is enlarged and centered on the page, enabling you to really put your conversational assistant in focus on your website, or to display the functionality to customers in a nice way.

Figure: Design Template 2 of the WebchatFigure: Design Template 2 of the Webchat

Figure: Design Template 2 of the Webchat

Versioning

We deploy the webchat into specific version folders on one of our servers. The baseUrl will always be: https://downloads.cognigy.com/CognigyWebchat, followed by a version name, followed by "cognigyWebChat.js". So release v1.1.5 of our webchat is at https://downloads.cognigy.com/CognigyWebchat/v1.1.5/cognigyWebChat.js.

Releases

The changelog for the WebChat can be found on github where this project is maintained:
https://github.com/Cognigy/CognigyWebChat/blob/master/changelog.md

1.1.10:
https://downloads.cognigy.com/CognigyWebchat/v1.1.10/cognigyWebChat.js

1.1.9:
https://downloads.cognigy.com/CognigyWebchat/v1.1.9/cognigyWebChat.js

1.1.8:
https://downloads.cognigy.com/CognigyWebchat/v1.1.8/cognigyWebChat.js

1.1.7:
https://downloads.cognigy.com/CognigyWebchat/v1.1.7/cognigyWebChat.js

1.1.6:
https://downloads.cognigy.com/CognigyWebchat/v1.1.6/cognigyWebChat.js

1.1.5:
https://downloads.cognigy.com/CognigyWebchat/v1.1.5/cognigyWebChat.js

1.1.4:
https://downloads.cognigy.com/CognigyWebchat/v1.1.4/cognigyWebChat.js

1.1.3:
https://downloads.cognigy.com/CognigyWebchat/v1.1.3/cognigyWebChat.js

1.1.2:
https://downloads.cognigy.com/CognigyWebchat/v1.1.2/cognigyWebChat.js

1.1.1:
https://downloads.cognigy.com/CognigyWebchat/v1.1.1/cognigyWebChat.js

1.1.0, released: 29.05.2018
https://downloads.cognigy.com/CognigyWebchat/v1.1.0/cognigyWebChat.js

Older versions are no longer available.

Modifying the Webchat

If you have an advanced use case that requires some modifications to the Webchat, then you can find the source code for the Webchat on our Github page.

Output Callback Function

Flows in COGNIGY.AI allow you to reply with more than just text, making them extremely powerful. You can send data, e.g. any JSON you want, in a Flow output, which you can use to render specific things on your page, trigger API calls and more. In order to accomplish this, the Webchat gives you the ability to pass in a callback function as the second parameter into the Cognigy.init() function, which will be executed on each Flow output, allowing you to do use-case specific things with the text and data that your Flow outputs. The callback function is called with one parameter, output, which is an object that contains text and data.

The example below uses a simple callback function that just console.logs the output tex
t and output data.

<body>
  <script type="text/javascript" src="https://downloads.cognigy.com/CognigyWebchat/v1.1.10/cognigyWebChat.js"></script>

  <script>
    const handleOutput = (output) => console.log(output.text, output.data);

    // Insert your own Config URL here
    Cognigy.init("https://endpoint-dev.cognigy.com/f22f3f35794fa49d6dd2449c3c38e1a9ed36b05a7d2388ab75e2ccac1f4ebbf9", handleOutput);
  </script>
</body>

Using the COGNIGY.AI Client to Send Messages

🚧

Requires version 1.1.1 of the Webchat

In some cases it might be necessary for you to send a message to your Flow from another point in your website than the Webchat. It can for instance be that you want to send an event to your Flow when your user clicks a certain button on your website.

In order to do this, the Webchat exposes the COGNIGY.AI client that you can use to send messages directly to your Flow. When you call the Cognigy.init function, the client is returned - either as a Promise or via a callback, depending on whether you need to support browsers that don't support Promises.

Getting the COGNIGY.AI Client from a Promise:

<body>
    <script type="text/javascript" src="https://downloads.cognigy.com/CognigyWebchat/v1.1.10/cognigyWebChat.js"></script>
  
    <script>
        Cognigy.init("https://endpoint-dev.cognigy.com/c89d63ef3179a3d17ab0f7a715b66a91ce48383cbd33fb3113aa5dfa0a1d8571", null)
          .then(client => console.log(client));
   
    </script>
</body>

Getting the COGNIGY.AI Client via a callback

<body>
    <script type="text/javascript" src="https://downloads.cognigy.com/CognigyWebchat/v1.1.10/cognigyWebChat.js"></script>
  
    <script>
      Cognigy.init("https://endpoint-dev.cognigy.com/c89d63ef3179a3d17ab0f7a715b66a91ce48383cbd33fb3113aa5dfa0a1d8571", null, (client) => console.log(client)) 
    </script>
</body>

client.sendMessage()


To send a message to your Flow with the COGNIGY.AI Client, you call its sendMessage function. The sendMessage function takes two arguments: text and data.

client.sendMessage(text, data);

Parameter

Type

text

string

data

object

The text and data you pass into the sendMessage function will be sent to your Flow.

<body>
    <script type="text/javascript" src="https://downloads.cognigy.com/CognigyWebchat/v1.1.10/cognigyWebChat.js"></script>
  
    <script>

        Cognigy.init("https://endpoint-dev.cognigy.com/c89d63ef3179a3d17ab0f7a715b66a91ce48383cbd33fb3113aa5dfa0a1d8571", null)
          .then(client => client.sendMessage("someText", { some: "data" }));
   
    </script>
</body>

📘

Sending text and data

You don't have to send text AND data, but can choose to leave one of them out. However, if both text and data are undefined / invalid, an error will be thrown.


Did this page help you?