Edit

Embed Your Webchat Channel

Overview

This process describes the installation of the Aisera Webchat bot (AiseraGPT application on the Aisera Webchat channel) on any portal or web landing page. This involves setting up session variables to pass information to the bot before loading it, and also the specific JavaScript code that should be used in the page layout to load the bot on the page.

JavaScript for Aisera Webchat Bots

The Aisera Webchat Bot is added by including a JavaScript(JS) Script on your page or portal. The following is an example script.

(function() {var d = document, s = d.createElement('script'); s.async = true; s.src = 'https://<your_tenant>.chatbot.aisera.<top_level_domain>/awc/js?t=a1b2c3d4-e5f6-7890-1234-567890abcdef' + Date.now(); d.getElementsByTagName('head')[0].appendChild(s)})();

To obtain this script:

  1. In the Aisera Admin UI navigate to Settings > AiseraGPT in the left navigation panel

  2. Select the bot with the Webchat Channel you would like to incorporate onto your page or portal

  3. In the AiseraGPT Details window under Channels click on the Webchat channel

  4. At the bottom of the Channel Details Page under the JavaScript Snippet click Copy

This script will contain all the relevant parameters for loading your bot on your page or portal.

Additional Configurations

Session Variables

Session variables can optionally be passed to Webchat in the window.aisera_bot global variable (or window.webchat for backward compatibility).

The following session variables have special meaning to Webchat:

  • userEmail: User email

  • userFullName: User full name

In addition to the user variables, other session variables could be specified to be used in custom flows.

For example:

window.aisera_bot = { 
    userEmail: "[email protected]", 
    userFullName: "John Smith", 
    accountId: "1234" 
}

If you specify userEmail in the session variables then you have to set the variable before the snippet that loads Webchat. It cannot be changed later using the update session vars message.

Below is an example showing session variables being passed to the webchat.

<html>
    <head>
        <script>
            window.webchat = {
                userEmail: "[email protected]",
                userFullName: "John Doe",
                locale: "fr",
            };
            (function () {
                var d = document,
                    s = d.createElement("script");
                s.async = true;
                s.src =
                    "https://<your_tenant>.chatbot.aisera.<top_level_domain>/awc/js?t=a1b2c3d4-e5f6-7890-1234-567890abcdef" +
                    Date.now();
                d.getElementsByTagName("head")[0].appendChild(s);
            })();
        </script>
    </head>
    <body>
        <h1>Sample page</h1>
    </body>
</html>

Input Messages

You can make a request to Webchat to perform operations using the window.postMessage function.

The JavaScript for these messages looks like the following:

let message = { 
    type: MESSAGE_TYPE, 
    // additional fields depending on the message type 
}; 

window.postMessage(JSON.stringify(message), "*");

The following input message types are supported:

Open

This message opens the application window if it is not already opened.

Field
Description

type

aisera.webchat.open

text

Optional text to be used as a search utterance

message

Optional html to be displayed in Webchat Other fields can be specified here and received in the opened output messages described below.

Close

This message closes the webchat window if it is not already closed

Field
Description

type

aisera.webchat.close

Reset

This message clears the webchat content and the current conversation contexts.

Field
Description

type

aisera.webchat.reset

Hide

This message hides the Webchat and the opener icon.

Field
Description

type

aisera.webchat.reset

Show

This message shows the Webchat and the opener icon if they are hidden using the aisera.webchat.hide message.

Field
Description

type

aisera.webchat.show

Update Session Vars

The hosting page can update the window.aisera_bot_variable at any time, but it needs to send this notification to notify the application.

Field
Description

type

aisera.webchat.update_session_vars

Output Messages

Webchat sends notification messages to the host window during specific operations.

The JavaScript that allows Webchat to receive the messages looks like the following:

window.addEventListener("message", event => {
    let message = JSON.parse(event.data);
    // use message.type etc
})

The following outgoing message types are supported:

Ready

This message is sent when Webchat is initialized and is ready to process messages.

Field
Description

type

aisera.webchat.ready

Opened

This message is sent when Webchat is opened. All fields specified in the open input message are included in the message.

Field
Description

type

aisera.webchat.opened

Closed

This message is sent when Webchat is closed.

Field
Description

type

aisera.webchat.closed

Handoff

This message is sent when a button with the Hand-off action is clicked.

Field
Description

type

aisera.webchat.handoff

transcript

The conversation transcript as a string

Session Timeout

This message is sent when the conversation session times out. The session times out when the user idle timeout configured in the Admin UI elapses.

Field
Description

type

aisera.webchat.session_timeout

Webchat Embed with an Iframe

To use your Webchat in an iframe inside a page containing a webchat snippet, change the URL in the snippet to include a target_id parameter with the iframe tag id.

For example, if the page has the following tag:

<iframe id=”webchat-iframe”</iframe>

The URL in the snippet should be changed to: 

https://{webchat-endpoint-url}&target_id=webchat-iframe

In order to embed the webchat in a browser window and take up the full width & height of the window, use &embed after the application endpoint URL.

https://{webchat-endpoint-url}&embed

In the embed mode, you can use the no_header URL parameter so the Webchat title bar is not displayed.

Session Variables passed as a URL Query Parameter

You can also pass session variables via query parameter as part of the URL.

  • Query parameter key: session_vars

  • Value: JSON Object

For example: 

https://{webchat-endpoint-url}&embed&session_vars={"userEmail":"[email protected]","user FullName":"John Smith","accountId":"1234"}

Hide Webchat and Open on Button Click

You can hide the Webchat opener using following CSS rule: 

#awc-webchat.closed {
   display:none 
}

Example of how to open Webchat on button click:

Open Webchat and Pass a Phrase as a URL Parameter

This is an example of a function that passes a phrase from the URL parameter into Webchat.

Webchat will automatically open and send this phrase as a request:

(function () {
    window.addEventListener("message", function (event) {
        try {
            // Web Chat events are stringified
            const { type } = JSON.parse(event.data);
            if (type === "aisera.webchat.internal.initialized") {
                // Then it's a Web Chat Initialized event.
                // Check whether an utterance to be triggered was provided.
                const queryString = window.location.search;
                const urlParams = new URLSearchParams(queryString);
                const text = urlParams.get("u");
                if (text) {
                    window.postMessage(
                        JSON.stringify({ type: "aisera.webchat.open", text }),
                        "*"
                    );
                }
            }
        } catch (error) {
            // Then `event.data` is NOT valid JSON which means it is not an Aisera WebChat event.
        }
    });
})();

PreviousCustomize SSO Failure Message

Last updated

Was this helpful?