HELP FILE

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: At admin.bold360.com, 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

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

Examples

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]);}