Customize a layered chat window using JavaScript

Take advantage of events and extend chat window features using JavaScript.

A layered chat window can trigger events during its life-cycle and allows you to work with JavaScript without restrictions.

Fastpath: In the Web Admin Center, go to Channels > Chat > Chat Windows > [New or existing window] > Customization.

Adding custom scripts

On the Customization tab, select Layered - Detailed and select the Includes key group. Includes allow you to inject JavaScript code and attach event listeners to chat windows with different scopes:

  • Chat Frame Javascript Include: Listeners and handlers run inside the iFrame object
  • Chat Window Javascript Include

What is the difference between a chat window and a chat frame?

Every layered chat window is comprised of a window and a frame object.

  • A chat window object is a container element that controls the window object of the host page, in which the chat window is embedded. As a consequence, listeners and handlers run outside the context of the iFrame object.
    Note: If the ancestor of a chat window is a separate window or tab, outside events, listeners and functions are not used.
  • A chat frame object is the window object of the innermost iFrame object, in which the chat runs.
    Note: If the ancestor of a chat window is a separate window object, the scope is the window object of the standalone window or tab.
Tip: Use the calledmobileChat variable to retrieve the object handle in use.

Using events and listeners

There are two ways to attach event listeners:

  • Use the mobileChat.addListener(eventName, eventHandler) method to register the handler.
    Important: eventName must be a valid event and eventHandler must be a callable function object, otherwise the listener throws an error.
  • Create a global function.
Tip: You can create more than one listener for an event in the following ways:
  • Mix the methods above
  • Call the addListener method more than once using the same event name
Note: A listener registered via the addListener method takes precedence, otherwise event handlers are executed in the order of registration.

Can I remove a registered listener? Calling the addListener method prevents the listener to be cleared. Global functions can be removed.

List of event functions

Table 1. iFrame events
Event Global function name Description Arguments
new-message bc_newHistoryMessageCallback New message added to chat history
  • integer personType
  • String messageText
  • DOMObject messageObject
chat-ended bc_chatEndedEventCallback Chat ended  
push-page bc_pushPageEventCallback A PushPage request sent by the agent and the customer accepts to be redirected to the target URL
  • String url
page-loaded bc_chatWindowLoadedEventCallback Page loaded  
resize bc_resizeEventCallback Elements resized  
Note: Events inside the iFrame object are forwarded to the context of the window object, but arguments may not be retained.
Table 2. window events
Event Global function name Description Arguments
new-message bc_newHistoryMessageCallback New message added to chat history
  • integer personType
  • String messageText
page-loaded bc_chatWindowLoadedEventCallback Page loaded  
chat-ended bc_chatEndedEventCallback Chat ended  
chat-closed bc_chatClosedEventCallback Chat closed  
push-page bc_pushPageEventCallback A PushPage request sent by the agent and the customer accepts to be redirected to the target URL
  • String url
resize bc_resizeEventCallback Elements resized  
maximized bc_chatWindowMaximizedEventCallback Frame maximized  
minimized bc_chatWindowMinimizeEventCallback Frame minimized  
Example:
 

The following snippets provide two different implementations of the same functionality.

  1. Create two listeners for every available event.
  2. Log the following to the console when an event is captured:
    • event name
    • event context
    • listener type
    • function name if the listener is a global function

iFrame object snippet (addListener method)

var _tEvents = {
        "new-message": "bc_newHistoryMessageCallback",
        "chat-closed": "bc_chatClosedEventCallback",
        "chat-ended": "bc_chatEndedEventCallback",
        "push-page": "bc_pushPageEventCallback",
        "page-loaded": "bc_chatWindowLoadedEventCallback",
        "resize": "bc_resizeEventCallback"
    },
    _tFunction = function(i, type, fName) {
        console.warn("event \"" + i + "\" captured inside the frame with " + type + (fName ? " (function name is '" + fName + "')" : ""));
    };
for (var i in _tEvents) {
    mobileChat.addListener(i, _tFunction.bind(window, i, "listener"));
    window[_tEvents[i]] = _tFunction.bind(window, i, "function", _tEvents[i]);
}

window object snippet (global function)

var _tEvents =  {
        "new-message": "bc_newHistoryMessageCallback",
        "resize": "bc_resizeEventCallback",
        "chat-closed": "bc_chatClosedEventCallback",
        "chat-ended": "bc_chatEndedEventCallback",
        "minimized": "bc_chatWindowMinimizeEventCallback",
        "maximized": "bc_chatWindowMaximizedEventCallback",
        "page-loaded": "bc_chatWindowLoadedEventCallback",
        "push-page": "bc_pushPageEventCallback"
    },
    _tFunction = function(i, type, fName) {
        console.warn("event \"" + i + "\" captured outside the frame with " + type + (fName ? " (function name is '" + fName + "')" : ""));
    };
for (var i in _tEvents) {
    mobileChat.addListener(i, _tFunction.bind(window, i, "listener"));
    window[_tEvents[i]] = _tFunction.bind(window, i, "function", _tEvents[i]);
}
Related Articles