Embed Your Webchat Channel

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

Use the following JavaScript code to load the Aisera Webchat Bot on any page.

This JS is applicable to the bot from an Aisera tenant and should be installed on the applicable customer portal.

(function(){var 
d=document,s=d.createElement('script');s.async=true;s.src='https://tenant.chatbot.aisera.cloud/awc/js?t=2ddd6a9a-c9cc-83ab-b8f2-7d21e623744d&'+Date.now();d.getElementsByTagName('head')[0].appendChild(s)})();

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" 
}

Note: 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 aisera.update_session_vars message (described below).

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 messages are supported:

Message

Description

aisera.webchat.open

This message opens the application window if it is not already opened. The message fields are: 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 aisera.webchat.opened output messages described below.

aisera.webchat.close

This message closes the Webchat window if it is not already closed. The message fields are:

type: aisera.webchat.close

aisera.webchat.reset

This message clears the Webchat content and the current conversation contexts. The message fields are:

type: aisera.webchat.reset

aisera.webchat.hide

This message hides the Webchat and the opener icon. The message fields are:

type: aisera.webchat.hide

aisera.webchat.show

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

type: aisera.webchat.show

aisera.update_session_vars

The hosting page can update the window.aisera_bot variable at any time, but it needs to send this message to notify the application. The message fields are:

type: aisera.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 messages are supported:

Message

Description

aisera.webchat.ready

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

The message fields are:

type: aisera.webchat.ready

aisera.webchat.opened

This message is sent when Webchat is opened. The message fields are:

type: aisera.webchat.opened

All fields specified in the aisera.webchat.open input message are included in the message.

aisera.webchat.closed

This message is sent when Webchat is closed.

The message fields are:

type: aisera.webchat.closed

aisera.webchat.handoff

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

The message fields are:

type: aisera.webchat.handoff

transcript: The conversation transcript as a String

aisera.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.

The message fields are:

type: aisera.session_timeout

Webchat Embed Mode

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>

then 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:

<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://{webchat-endpoint-url}&'+`locale=`+'fr'+`&`+Date.now();
        d.getElementsByTagName('head')[0].appendChild(s)
    })();
    </script>

</head>

<body>
Sample page
</body>

</html>

The following code can be used to pass in the user's email and locale to your application.

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 Web
Chat event.
}
});
})();

Webchat Integration Examples

The following examples describe how to use variables to fill in user information.

Webchat Invocation where userEmail is filled in Programmatically

The following code can be used to pass in the full name and email of the user to Webchat.

(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 Webchat 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 Web
  Chat event.
  }
 });
})();

Webchat Invocation where userEmail and locale is set Programmatically

The following code can be used to pass in the user email and locale to Webchat.

<html>
<head>

    <script>
    window.webchat = {
        userEmail: "[email protected]",
        userFullName: "John Doe"
    };
    (function(){
      var d=document,s=d.createElement('script');
      s.async=true;
      s.src='https://{webchat-endpoint-url}&'+Date.now();
      d.getElementsByTagName('head')[0].appendChild(s)
    })();

    </script>

</head>
</html>

PreviousCustomize SSO Failure Message

Last updated 11 months ago