Chat Widget API

Chat Widget API allows you to manipulate the chat widget displayed on your website. Thanks to the ChatBot API you can control the chat window, change the default chat bubble to custom image and much more. Below you will find a complete list of all methods available in ChatBot.

There are two types of methods that can be used to control the chat window:

• Hooks - are triggered when the specific action occurs (for example, when chat widget is opened or closed).
• Methods - can be triggered in any part of your code, can also be combined with hooks (for example, when chat widget is opened, send specific message).

You can use both Hooks and Methods along with other methods available in your code. For example, you can send Google Analytics event whenever the chat window is opened (onChatWindowOpen), or use logged in user data and pass it to your bot story, so you won’t have to ask for their email addess again during the chat (setUserAttributes).

Available methods

• Hooks

  • onBeforeLoad - invoked when widget code is loaded but chat window is not rendered yet,
  • onLoad - invoked when widget code is loaded and chat window is rendered,
  • onDestroy - invoked after destroy() API method call,
  • onSessionReset - invoked after resetSession() API method call,
  • onChatWindowOpen - invoked when the chat window is opened,
  • onChatWindowClose - invoked when the chat window is closed,
  • onChatWindowHide - invoked when the chat window is hidden,
  • onMessage - invoked after query result,
  • onConversationStart - invoked after the conversation starts,
  • onConversationEnd - invoked after the conversation ends

• Methods

  • create - creates Chat Widget if it does not exist,
  • destroy - destroys Chat Widget if it exist,
  • isInitialized - returns true if the chat is initialized,
  • resetSession - resets current session and recreates Chat Widget,
  • openChatWindow - opens the Chat Widget,
  • closeChatWindow - closes the Chat Widget,
  • hideChatWindow - hides the Chat Widget,
  • isChatWindowOpened - returns true if the chat window is open,
  • isChatWindowClosed - returns true if the chat window is closed,
  • isChatWindowHidden - returns true if the chat window is hidden,
  • sendMessage - sends a message as a visitor,
  • setUserAttributes - used for setting User Attributes,
  • setSessionAttributes - used for setting Session Attributes

Hooks

onBeforeLoad

Callback function invoked when widget code is loaded but chat window is not rendered yet. You can return false to stop the widget initialization.

window.BE_API = window.BE_API || {};
window.BE_API.onBeforeLoad = function () {
    // return false
};

onLoad

Callback function invoked when widget code is loaded and chat window is rendered.

window.BE_API = window.BE_API || {};
window.BE_API.onLoad = function () {
    // ...
};

onDestroy

Callback function invoked after destroy() API method call.

window.BE_API = window.BE_API || {};
window.BE_API.onDestroy = function () {
    // ...
};

onSessionReset

Callback function invoked after resetSession() API method call.

window.BE_API = window.BE_API || {};

window.BE_API.onSessionReset = function () {
    // ...
};

onChatWindowOpen

Callback function invoked when the chat window is opened.

window.BE_API = window.BE_API || {};
window.BE_API.onChatWindowOpen = function () {
    // ...
};

onChatWindowClose

Callback function invoked when the chat window is closed.

window.BE_API = window.BE_API || {};
window.BE_API.onChatWindowClose = function () {
    // ...
};

onChatWindowHide

Callback function invoked when the chat window is hidden.

window.BE_API = window.BE_API || {};
window.BE_API.onChatWindowHide = function () {
    // ...
};

onMessage

Callback function invoked after query result.

window.BE_API = window.BE_API || {};
window.BE_API.onMessage = function (result) {
    console.log(result)
};

onConversationStart

Callback function invoked after the conversation starts.

window.BE_API = window.BE_API || {};
window.BE_API.onConversationStart = function () {
    // ...
};

onConversationEnd

Callback function invoked after the conversation ends.

window.BE_API = window.BE_API || {};
window.BE_API.onConversationEnd = function () {
    // ...
};

Methods

create

Create chat widget if does not exist

window.BE_API = window.BE_API || {};
window.BE_API.onLoad = function () {
    window.BE_API.create();
};

destroy

Destroy chat widget if exist

window.BE_API = window.BE_API || {};
window.BE_API.onLoad = function () {
    window.BE_API.destroy();
};

isInitialized

Returns true if the chat is initialized.

window.BE_API = window.BE_API || {};
window.BE_API.onLoad = function () {
    window.BE_API.isInitialized();
};

resetSession

Reset current session and recreate widget.

window.BE_API = window.BE_API || {};
window.BE_API.onLoad = function () {
    window.BE_API.resetSession();
};

openChatWindow

Open the chat window, should be used only inside window.BE_API.onLoad callback

window.BE_API = window.BE_API || {};
window.BE_API.onLoad = function () {
    window.BE_API.openChatWindow();
};

closeChatWindow

Close the chat window, should be used only inside window.BE_API.onLoad callback

window.BE_API = window.BE_API || {};
window.BE_API.onLoad = function () {
    window.BE_API.closeChatWindow();
};

hideChatWindow

Hide the chat window, should be used only inside window.BE_API.onLoad callback

window.BE_API = window.BE_API || {};
window.BE_API.onLoad = function () {
    window.BE_API.hideChatWindow();
};

isChatWindowOpened

Should be used only inside window.BE_API.onLoad callback. Returns true if the chat window is open.

window.BE_API = window.BE_API || {};
window.BE_API.onLoad = function () {
    window.BE_API.isChatWindowOpened();
};

isChatWindowClosed

Should be used only inside window.BE_API.onLoad callback. Returns true if the chat window is closed.

window.BE_API = window.BE_API || {};
window.BE_API.onLoad = function () {
    window.BE_API.isChatWindowClosed();
};

isChatWindowHidden

Should be used only inside window.BE_API.onLoad callback. Returns true if the chat window is hidden.

window.BE_API = window.BE_API || {};
window.BE_API.onLoad = function () {
    window.BE_API.isChatWindowHidden();
};

setUserAttributes

Set user attributes. Read more about user attributes here.

window.BE_API = window.BE_API || {};
window.BE_API.onLoad = () => {
    window.BE_API.setUserAttributes({
        email: 'support@chatbot.com',
        name: 'ChatBot Support'
    })
}

Payload

Payload should contain all User Attributes that should be set when the method is called.

Entry Object

Entry Object consist of key/value pairs, which define the attribute name and value.

setSessionAttributes

Set your custom attributes that will be sent to the query. Each method call will overwrite existing parameters. Read more about attributes here.

window.BE_API = window.BE_API || {};
window.BE_API.onLoad = () => {
    window.BE_API.setSessionAttributes({
        email: 'support@chatbot.com',
        name: 'ChatBot Support'
    })
}

Payload

Payload should contain all Session Attributes that should be set when the method is called.

Entry Object

Entry Object consist of key/value pairs, which define the attribute name and value.

sendMessage

Send a message as visitor.

window.BE_API = window.BE_API || {};
window.BE_API.onLoad = () => {
    window.BE_API.sendMessage({
        message: 'message',
        postback: 'postback'
    })
}

Payload

Payload must contain the message content. It can also send postback to the bot when it’s delivered.