API Reference

Welcome to the tawk.to JavaScript API documentation.

The API provides a flexible set of methods that can be used in your web projects. To invoke one of the methods below, please be sure to call a method after the embed code on your page.

Use the JavaScript API to manipulate the chat widget displayed on your website.

load
statusChange
beforeLoad
chatMaximized
chatMinimized
chatHidden
chatStarted
chatEnded
prechatSubmit
offlineSubmit
chatMessageVisitor
chatMessageAgent
chatMessageSystem
agentJoinChat
agentLeaveChat
chatSatisfaction
visitorNameChanged
fileUpload
tagsUpdated
unreadCountChanged
visitor
maximize
minimize
toggle
popup
getWindowType
showWidget
hideWidget
toggleVisibility
getStatus
isChatMaximized
isChatMinimized
isChatHidden
isChatOngoing
isVisitorEngaged
onLoaded
onBeforeLoaded
widgetPosition
endChat
setAttributes
addEvent
addTags
removeTags
secureMode
customStyle

load

Listen on event that invoked right after the widget is rendered. This is not supported in pop out chat window.

this.$tawkMessenger.$on('load', () => {
    // place your code here
});

statusChange

Listen on event that invoked when the page status changes. The function will receive the changed status which will be either online, away or offline. This is not supported in pop out chat window.

this.$tawkMessenger.$on('statusChage', (status) => {
    // place your code here
});

beforeLoad

Listen on event that invoked right when Tawk_API is ready to be used and before the widget is rendered. This is not supported in pop out chat window.

this.$tawkMessenger.$on('beforeLoad', () => {
    // place your code here
});

chatMaximized

Listen on event that invoked when the widget is maximized. This is not supported in pop out chat window.

this.$tawkMessenger.$on('chatMaximized', () => {
    // place your code here
})

chatMinimized

Listen on event that invoked when the widget is minimized. This is not supported in pop out chat window.

this.$tawkMessenger.$on('chatMinimized', () => {
    // place your code here
});

chatHidden

Listen on event that invoked when the widget is hidden. This is not supported in pop out chat window.

this.$tawkMessenger.$on('chatHidden', () => {
    // place your code here
});

chatStarted

Listen on event that invoked when the widget is started.

this.$tawkMessenger.$on('chatStarted', () => {
    // place your code here
});

chatEnded

Listen on event that invoked when the widget is ended. This is not supported in pop out chat window.

this.$tawkMessenger.$on('chatEnded', () => {
    // place your code here
});

prechatSubmit

Listen on event that invoked when the Pre-Chat Form is submitted. The submitted form data is passed to the function. This is not supported in pop out chat window.

this.$tawkMessenger.$on('prechatSubmit', (data) => {
    // place your code here
});

offlineSubmit

Listen on event that invoked when the Offline form is submitted. The submitted form data is passed to the function. Form data will contain {name : ”, email : ”, message : ”, questions : []}. This is not supported in pop out chat window.

this.$tawkMessenger.$on('offlineSubmit', (data) => {
    // place your code here
});

chatMessageVisitor

Listen on event that invoked when message is sent by the visitor. The message is passed to the function. This is not supported in pop out chat window.

this.$tawkMessenger.$on('chatMessageVisitor', (message) => {
    // place your code here
});

chatMessageAgent

Listen on event that invoked when message is sent by the agent. The message is passed to the function. This is not supported in pop out chat window.

this.$tawkMessenger.$on('chatMessageAgent', (message) => {
    // place your code here
});

chatMessageSystem

Listen on event that invoked when message is sent by the system. The message is passed to the function. This is not supported in pop out chat window.

this.$tawkMessenger.$on('chatMessageSystem', (message) => {
    // place your code here
});

agentJoinChat

Listen on event that invoked when an agent joins the chat. The data is passed to the function. Will contain {name : ”, position : ”, image : ”, id : ”}. This is not supported in pop out chat window.

this.$tawkMessenger.$on('agentJoinChat', (data) => {
    // place your code here
});

agentLeaveChat

Listen on event that invoked when an agent leaves the chat. The data is passed to the function. Will contain {name : ”, id : ”}. This is not supported in pop out chat window.

this.$tawkMessenger.$on('agentLeaveChat', (data) => {
    // place your code here
});

chatSatisfaction

Listen on event that invoked when an agent leaves the chat. The satisfaction is passed to the function. -1 = dislike | 0 = neutral | 1 = like. This is not supported in pop out chat window.

this.$tawkMessenger.$on('chatSatisfaction', (satisfaction) => {
    // place your code here
});

visitorNameChanged

Listen on event that invoked when the visitor manually changes his name. The visitorName is passed to the function. This is not supported in pop out chat window.

this.$tawkMessenger.$on('visitorNameChanged', (visitorName) => {
    // place your code here
});

fileUpload

Listen on event that invoked when a file is uploaded. The link to the uploaded file is passed to the function. This is not supported in pop out chat window.

this.$tawkMessenger.$on('fileUpload', (link) => {
    // place your code here
});

tagsUpdated

Listen on event that invoked when a tag is updated.

this.$tawkMessenger.$on('tagsUpdated', (data) => {
    // place your code here
});

unreadCountChanged

Listen on event that returns count of unread messages.

this.$tawkMessenger.$on('unreadCountChanged', (count) => {
    // place your code here
});

visitor

Object used to set the visitor name and email. Do not place this object in a function, as the values need to be available before the widget script is downloaded.

Setting or changing the values after the widget script has been downloaded will not send the values to the dashboard.

If the name and email will not be available on load time (eg single page app, ajax login), then use the setAttributes function instead.

this.$tawkMessenger.visitor({
    name : 'Name',
    email : 'email@email.com'
});

maximize

Maximizes the chat widget.

this.$tawkMessenger.maximize();

// Example

this.$tawkMessenger.$on('load', () => {
    this.$tawkMessenger.maximize();
});

minimize

Minimizes the chat widget.

this.$tawkMessenger.minimize();

// Example

this.$tawkMessenger.$on('load', () => {
    this.$tawkMessenger.minimize();
});

toggle

Minimizes or Maximizes the chat widget based on the current state.

this.$tawkMessenger.toggle();

// Example

this.$tawkMessenger.$on('load', () => {
    this.$tawkMessenger.toggle();
});

popup

Opens the chat widget as a pop out.

this.$tawkMessenger.popup();

// Example

this.$tawkMessenger.$on('load', () => {
    this.$tawkMessenger.popup();
});

getWindowType

Returns the current widget type whether it’s inline or embed.

this.$tawkMessenger.getWindowType();

// Example

this.$tawkMessenger.$on('load', () => {
    if (this.$tawkMessenger.getWindowType() === 'inline') {
        // do something if it's inline
    } else {
        // do something if it's embed
    }
});

showWidget

Shows the chat widget.

this.$tawkMessenger.showWidget();

// Example

this.$tawkMessenger.$on('load', () => {
    this.$tawkMessenger.showWidget();
});

hideWidget

Hide the chat widget.

this.$tawkMessenger.hideWidget();

// Example

this.$tawkMessenger.$on('load', () => {
    this.$tawkMessenger.hideWidget();
});

toggleVisibility

Hides or Shows the chat widget based on the current visibility state.

this.$tawkMessenger.toggleVisibility();

// Example

this.$tawkMessenger.$on('load', () => {
    this.$tawkMessenger.toggleVisibility();
});

getStatus

Returns the current page status (online, away or offline).

this.$tawkMessenger.getStatus();

// Example

this.$tawkMessenger.$on('load', () => {
    const pageStatus = this.$tawkMessenger.getStatus();

    if (pageStatus === 'online') {
        // do something for online
    } else if (pageStatus === 'away') {
        // do something for away
    } else {
        // do something for offline
    }
});

isChatMaximized

Returns a boolean value (true or false) indicating whether the chat widget is maximized.

this.$tawkMessenger.isChatMaximized();

// Example

this.$tawkMessenger.$on('load', () => {
    if (this.$tawkMessenger.isChatMaximized()) {
        // do something it it's maximized
    }
});

isChatMinimized

Returns a boolean value (true or false) indicating whether the chat widget is minimized.

this.$tawkMessenger.isChatMinimized();

// Example

this.$tawkMessenger.$on('load', () => {
    if (this.$tawkMessenger.isChatMinimized()) {
        // do something if it's minimized
    }
});

isChatHidden

Returns a boolean value (true or false) indicating whether the chat widget is hidden.

this.$tawkMessenger.isChatHidden();

// Example

this.$tawkMessenger.$on('load', () => {
    if (this.$tawkMessenger.isChatHidden()) {
        // do something if chat widget is hidden
    }
});

isChatOngoing

Returns a boolean value (true or false) indicating whether currently there is an ongoing chat.

this.$tawkMessenger.isChatOngoing();

// Example

this.$tawkMessenger.$on('load', () => {
    if (this.$tawkMessenger.isChatOngoing()) {
        // do something if there's ongoing chat
    }
});

isVisitorEngaged

Returns a boolean value (true or false) indicating whether the visitor is currently chatting or has requested a chat.

this.$tawkMessenger.isVisitorEngaged();

// Example

this.$tawkMessenger.$on('load', () => {
    if (this.$tawkMessenger.isVisitorEngaged()) {
        // do something if visitor engaged in chat
    }
});

onLoaded

Returns a boolean value (true or undefined) indicating when the plugin is ready.

this.$tawkMessenger.onLoaded();

// Example
if (this.$tawkMessenger.onLoaded()) {
    // do something when widget is ready
}

onBeforeLoaded

Returns a boolean value (true or undefined) indicating when plugin is initialize.

this.$tawkMessenger.onBeforeLoaded();

// Example
if (this.$tawkMessenger.onBeforeLoaded()) {
    // do something before onload
}

widgetPosition

Returns a string for current position of the widget.

this.$tawkMessenger.widgetPosition();

// Example
this.$tawkMessenger.$on('load', () => {
    if (this.$tawkMessenger.widgetPosition() === 'br') {
        // do something if the widget is at bottom right
    }
});

endChat

Ends the current ongoing chat.

this.$tawkMessenger.endChat();

// Example

this.$tawkMessenger.$on('load', () => {
    this.$tawkMessenger.endChat();
});

setAttributes

Set custom metadata regarding this chat/visitor.

This function takes in two values: attribute and callback.

The attribute value is of the object data type, which is a key value pair.

The key is of the string data type and can contain only alphanumeric characters and ‘-‘ (dash).

You can also use this function to set the visitor name and email. However, you will need to enable the secure mode first and also supply the calculated hash value in this function.

Refer to the secure mode section below on how to do this.

The reason it needs to be in secure mode is to ensure data integrity — to ensure the value sent from the widget to the dashboard is true and has not been tampered with.

The callback, which is a function, will be invoked to notify whether the save failed.

Error messages returned:

INVALID_ATTRIBUTES: No attributes were sent
SESSION_EXPIRED: The visitor’s current session has expired
SERVER_ERROR: Internal server error
ACCESS_ERROR: Error in accessing the page
ATTRIBUTE_LIMIT_EXCEEDED: Total custom attributes (excluding name, email and hash) is 50
CONTAINS_INVALID_KEY: Custom key is not alphanumeric or dash (keys will be lower case)
CONTAINS_INVALID_VALUE: Custom value is empty or the total length is more than 255 characters

this.$tawkMessenger.setAttributes(attributes, callback);

// Example

this.$tawkMessenger.$on('load', () => {
    this.$tawkMessenger.setAttributes({
            id : 'A1234',
            store : 'Midvalley'
        }, function(error) {
            // do something if error
        });
});

// Example for setting name and email

this.$tawkMessenger.$on('load', () => {
    this.$tawkMessenger.setAttributes({
            name : 'Name',
            email : 'email@email.com',
            hash : 'hash value'
        }, function(error) {
            // do something if error
        });
});

addEvent

Set a custom event to chat. This function takes in 3 values: event name, optional metadata and callback.

The event name is of the string data type and can contain only alphanumeric characters and ‘-‘ (dash)

The callback which is a function will be invoked to notify whether the save failed.

INVALID_EVENT_NAME, INVALID_ATTRIBUTES, ATTRIBUTE_LIMIT_EXCEEDED, CONTAINS_INVALID_KEY, CONTAINS_INVALID_VALUE, SESSION_EXPIRED, SERVER_ERROR

this.$tawkMessenger.addEvent(eventName, metaData, callback);

// Example

this.$tawkMessenger.$on('load', () => {
    this.$tawkMessenger.addEvent(
        'requested-quotation',
        function(error) {
            // do something if error
        }
    );

    this.$tawkMessenger.addEvent(
        'product-add-to-cart',
        {
            sku : 'A0012',
            name : 'Jeans',
            price : '50'
        },
        function(error) {
            // do something if error
        }
    );
});

addTags

Add tags to the chat. This function takes in two values; tags and callback. This is of the array data type. The content of the tags should be of the string data type.

The total number of tags is 10. The callback, which is a function, will be invoked to notify whether the save failed.

INVALID_TAGS, TAG_LIMIT_EXCEEDED, VERSION_CONFLICT, SESSION_EXPIRED, SERVER_ERROR

$tawkMessengerVue.addTags(tags, callback);

// Example

this.$tawkMessenger.$on('load', () => {
    this.$tawkMessenger.addTags(
        [
            'hello',
            'world'
        ],
        function(error) {
            // do something if error
        }
    );
});

removeTags

Remove tags from the chat. This function takes in two values: tags and callback. This is of the array data type. The content of the tags should be of the string data type.

The callback, which is a function, will be invoked to notify whether the save failed.

INVALID_TAGS, TAG_LIMIT_EXCEEDED, SESSION_EXPIRED, SERVER_ERROR

$tawkMessengerVue.removeTags(tags, callback);

// Example

this.$tawkMessenger.$on('load', () => {
    this.$tawkMessenger.removeTags(
        [
            'hello',
            'world'
        ],
        function (error) {
            // do something if error
        }
    );
});

secureMode

Secure method is to ensure the data you are sending is actually from you.

To enable secure mode, embed following code on your page.

The hash is server side generated HMAC using SHA256, the user’s email and your site’s API key.

You can get your API key from Admin>Property Settings.

this.$tawkMessenger.visitor({
    name : 'Name',
    email : 'email@email.com',
    hash : '<calculate-hash>'
})

customstyle

Object used to update the widget styling. Currently only supports zIndex style. Do not place this object in a function, as the values need to be available before the widget script is downloaded. Setting or changing the values after the widget script has been downloaded will not update the widget’s style.

zIndex

// ZIndex
Vue.use(TawkMessengerVue, {
    customStyle : {
        zIndex : Integer | String 
    }
});

// Example

Vue.use(TawkMessengerVue, {
    customStyle : {
        zIndex : 1000
    }
});

Vue.use(TawkMessengerVue, {
    customStyle : {
        zIndex : '1000'
    }
});

Vue.use(TawkMessengerVue, {
    customStyle : {
        zIndex : '1000 !important'
    }
});

Visibility

// ZIndex
Vue.use(TawkMessengerVue, {
    customStyle : {
        visibility : {
            dekstop : {
                xOffset : String | Integer, // '20' || 20
                yOffset : String | Integer,
                position : '' // 'br', 'bl', 'cr', 'cl', 'tr', 'tl'
            },

            mobile : {
                xOffset : String | Integer, // '20' || 20
                yOffset : String | Integer,
                position : '' // 'br', 'bl', 'cr', 'cl', 'tr', 'tl'
            }
        }
    }
});

// Example

Vue.use(TawkMessengerVue, {
    customStyle : {
        visibility : {
            dekstop : {
                xOffset : '15',
                yOffset : '15',
                position : 'cr'
            },

            mobile : {
                xOffset : 15,
                yOffset : 15,
                position : 'bl'
            }
        }
    }
});

Files

api-reference.md

Latest commit

History

api-reference.md

File metadata and controls

API Reference

Table of contents

load

statusChange

beforeLoad

chatMaximized

chatMinimized

chatHidden

chatStarted

chatEnded

prechatSubmit

offlineSubmit

chatMessageVisitor

chatMessageAgent

chatMessageSystem

agentJoinChat

agentLeaveChat

chatSatisfaction

visitorNameChanged

fileUpload

tagsUpdated

unreadCountChanged

visitor

maximize

minimize

toggle

popup

getWindowType

showWidget

hideWidget

toggleVisibility

getStatus

isChatMaximized

isChatMinimized

isChatHidden

isChatOngoing

isVisitorEngaged

onLoaded

onBeforeLoaded

widgetPosition

endChat

setAttributes

addEvent

addTags

removeTags

secureMode

customstyle

zIndex

Visibility