JavaScript API | tawk.to

Introduction

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

Some popular use–cases are:

We are always excited to see how you use the API, so feel free to share your creations with us!
onLoad
Callback function invoked right after the widget is rendered. This callback is not supported in pop out chat window. 
Tawk_API = Tawk_API || {};
Tawk_API.onLoad = function(){
    //place your code here
};
onStatusChange
Callback function invoked when the page status changes. The function will receive the changed status which will be either online, away or offline. This callback is not supported in pop out chat window. 
Tawk_API = Tawk_API || {};
Tawk_API.onStatusChange = function(status){
    //place your code here
};
onBeforeLoad
Callback function invoked right when Tawk_API is ready to be used and before the widget is rendered. This callback is not supported in pop out chat window. 
Tawk_API = Tawk_API || {};
Tawk_API.onBeforeLoad = function(){
    //place your code here
};
onChatMaximized
Callback function invoked when the widget is maximized. This callback is not supported in pop out chat window. 
Tawk_API = Tawk_API || {};
Tawk_API.onChatMaximized = function(){
    //place your code here
};
onChatMinimized
Callback function invoked when the widget is minimized. This callback is not supported in pop out chat window. 
Tawk_API = Tawk_API || {};
Tawk_API.onChatMinimized = function(){
    //place your code here
};
onChatHidden
Callback function invoked when the widget is hidden. This callback is not supported in pop out chat window. 
Tawk_API = Tawk_API || {};
Tawk_API.onChatHidden = function(){
    //place your code here
};
onChatStarted
Callback function invoked when the widget is started.
Tawk_API = Tawk_API || {};
Tawk_API.onChatStarted = function(){
    //place your code here
};
onChatEnded
Callback function invoked when the widget is ended. This callback is not supported in pop out chat window. 
Tawk_API = Tawk_API || {};
Tawk_API.onChatEnded = function(){
    //place your code here
};
onPrechatSubmit
Callback function invoked when the prechat form submitted. The submitted form data is passed to the function. This callback is not supported in pop out chat window. 
Tawk_API = Tawk_API || {};
Tawk_API.onPrechatSubmit = function(data){
    //place your code here
};
onOfflineSubmit
Callback function invoked when the offline form submitted. The submitted form data is passed to the callback. Form data will contain {name : '', email : '', message : '', questions : []} . This callback is not supported in pop out chat window. 
Tawk_API = Tawk_API || {};
Tawk_API.onOfflineSubmit = function(data){
    //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 needs 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.

Tawk_API = Tawk_API || {};
Tawk_API.visitor = {
    name  : 'Name',
    email : '[email protected]'
};
maximize();
Maximizes the chat widget. 
Tawk_API.maximize();

//Example

Tawk_API.onLoad = function(){
    Tawk_API.maximize();
};
minimize();
Minimizes the chat widget. 
Tawk_API.minimize();

//Example

Tawk_API.onLoad = function(){
    Tawk_API.minimize();
};
toggle();
Minimizes or Maximizes the chat widget based on the current state. 
Tawk_API.toggle();

//Example

Tawk_API.onLoad = function(){
    Tawk_API.toggle();
};
popup();
Opens the chat widget as a pop out.
Tawk_API.popup();

//Example

Tawk_API.onLoad = function(){
    Tawk_API.popup();
};
getWindowType();
Returns the current widget type whether it's inline or embed.
Tawk_API.getWindowType();

//Example

Tawk_API.onLoad = function(){
    if(Tawk_API.getWindowType() === 'inline'){
        // do something if it's inline
    }else{
        // do something if it's embed
    }
};
showWidget();
Shows the chat widget.
Tawk_API.showWidget();

//Example

Tawk_API.onLoad = function(){
    Tawk_API.showWidget();
};
hideWidget();
Hides the chat widget.
Tawk_API.hideWidget();

//Example

Tawk_API.onLoad = function(){
    Tawk_API.hideWidget();
};
toggleVisibility();
Hides or Shows the chat widget based on the current visibility state.
Tawk_API.toggleVisibility();


//Example

Tawk_API.onLoad = function(){
    Tawk_API.toggleVisibility();
};
getStatus();
Returns the current page status (online, away or offline).
Tawk_API.getStatus();

//Example

Tawk_API.onLoad = function(){
    var pageStatus = Tawk_API.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) whether the chat widget is maximized.
Tawk_API.isChatMaximized();


//Example

Tawk_API.onLoad = function(){
    if(Tawk_API.isChatMaximized()){
        //do something if it's maximized
    }
};
isChatMinimized();
Returns a boolean value (true or false) whether the chat widget is minimized.
Tawk_API.isChatMinimized();


//Example

Tawk_API.onLoad = function(){
    if(Tawk_API.isChatMinimized()){
        // do something if it's minimized
    }
};
isChatHidden();
Returns a boolean value (true or false) whether the chat widget is hidden.
Tawk_API.isChatHidden();

//Example

Tawk_API.onLoad = function(){
    if(Tawk_API.isChatHidden()){
        // do something if chat widget is hidden
    }
};
isChatOngoing();
Returns a boolean value (true or false) whether currently there is an ongoing chat.
Tawk_API.isChatOngoing();

//Example

Tawk_API.onLoad = function(){
    if(Tawk_API.isChatOngoing()){
        // do something is there's ongoing chat
    }
};
isVisitorEngaged();
Returns a boolean value (true or false) whether the visitor is currently chatting or has requested a chat.
Tawk_API.isVisitorEngaged();

//Example

Tawk_API.onLoad = function(){
    if(Tawk_API.isVisitorEngaged()){
        // do something if visitor is engaged in chat
    }
};
endChat();
Ends the current ongoing chat.
Tawk_API.endChat();

//Example

Tawk_API.onLoad = function(){
    Tawk_API.endChat();
};
setAttributes();

Set custom metadata regarding this chat / visitor.
This function takes in two values; attribute and callback;
The attribute value is of 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 supply the calculated hash value in this function too.
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 that the value sent from the widget to the dashboard is the truth and has not been tampered with.

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

Errors message returned :

  1. INVALID_ATTRIBUTES : No attributes was sent
  2. SESSION_EXPIRED : The visitor's current session has expired
  3. SERVER_ERROR : Internal server error
  4. ACCESS_ERROR : Error in accessing the page
  5. ATTRIBUTE_LIMIT_EXCEEDED : Total custom attributes (excluding name, email and hash) is 50
  6. CONTAINS_INVALID_KEY : Custom key is not alphanumeric or dash (keys will be lowercased)
  7. CONTAINS_INVALID_VALUE : Custom value is empty or the total length is more than 255 characters

Tawk_API.setAttributes(attributes, callback);

//Example

Tawk_API.onLoad = function(){
    Tawk_API.setAttributes({
        'id'    : 'A1234',
        'store' : 'Midvalley'
    }, function(error){});
};


//Example for setting name and email

Tawk_API.onLoad = function(){
    Tawk_API.setAttributes({
        'name'  : 'Name',
        'email' : '[email protected]',
        'hash'  : 'hash value'
    }, function(error){});
}
addEvent();
Set a custom event to chat.
This function takes in 3 values; event name, an optional metadata and callback function.

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
Tawk_API.addEvent(eventName, metadata, callback);

//Example

Tawk_API.onLoad = function(){
    Tawk_API.addEvent('requested-quotation', function(error){});

    Tawk_API.addEvent('product-add-to-cart', {
        'sku'    : 'A0012',
        'name'  : 'Jeans',
        'price' :'50'
    }, function(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 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 
Tawk_API.addTags(tags, callback);

//Example

Tawk_API.onLoad = function(){
    Tawk_API.addTags(['hello', 'world'], function(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 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
Tawk_API.removeTags(tags, callback);

//Example

Tawk_API.onLoad = function(){
    Tawk_API.removeTags(['hello', 'world'], function(error){});
};
Secure Mode
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, using the user's email and your site's API key.
You can get your API key from Admin->Property Settings.
Tawk_API = Tawk_API || {};
Tawk_API.visitor = {
    name  : 'Name',
    email : '[email protected]',
    hash  : '<calculate-hash>'
};

// Here is an example how you could do it using PHP

Tawk_API = Tawk_API || {};
Tawk_API.visitor = {
    name  : '<?php echo $user->name; ?>',
    email : '<?php echo $user->email; ?>',
    hash  : '<?php echo hash_hmac("sha256", $user->email, "<API-KEY>"); ?>'
};
×