JavaScript API

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.

Popular use-cases:

We are always excited to see how you use the API, so feel free to share your creations with us!

Reference:

autoStart

This option allows you to disable the auto start connection of the chat widget.

You have the option to disable autoStart after the widget loads on your website. By default, this is set to true. When autoStart is disabled, the widget will be hidden by default on load.


window.Tawk_API.autoStart = false;

// Example

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.autoStart = false;

start

Manually Initiate the connection for the chat widget.

This method is used to explicitly start the socket connection of the chat widget. In the provided example, window.Tawk_API.start() is called when the chat status changes to ‘online’, demonstrating a scenario where you might want to initiate the widget’s socket connection based on its status.

You can also add the option showWidget to true. When the widget successfully starts the connection, the widget will be displayed on your website.


window.Tawk_API.start();

// Example

window.Tawk_API.onStatusChange = function(status){
    if (status === 'online') {
       window.Tawk_API.start();
    }
};

// Show widget when connection starts
window.Tawk_API.onStatusChange = function(status){
    if (status === 'online') {
       window.Tawk_API.start({
          showWidget : true
       });
   }
};

shutdown

This method disconnects the socket connection of the chat widget.

Use this method when you want to explicitly disconnect the chat widget’s socket connection. In the provided example, window.Tawk_API.shutdown() is triggered when the chat is minimized, demonstrating a scenario where you might want to disconnect the widget.


window.Tawk_API.shutdown();

// Example

window.Tawk_API.onChatMinimized = function(){
     window.Tawk_API.shutdown();
};

switchWidget

This function allows you to switch to another widget. If you have multiple widgets, you can utilize this new API function for seamless switching.

Use this function to switch between widgets by providing the appropriate propertyId and widgetId in the data object. The optional callback function allows you to execute specific actions after the widget switch, and you can handle errors within the callback if necessary.


window.Tawk_API.switchWidget(data, callback);

// Example

window.Tawk_API.switchWidget({
     propertyId : 'your-property-id',
     widgetId : 'your-widget-id'
}, function(error) {
   if (error) {
      // do something if error
   }

// do something after switching to another widget

});

login

This function will login a user using hash and userId. This will retrieved the conversation of the user if it has existing before.

This function will refresh and reconnect the session when called.

userId property will be a string that will be provided by the third party users.

hash is a combination of userId + site API key using HMAC SHA256

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

You can also set the optional properties like name, email and phone.

This function supports set attributes by adding the custom attributes in the object.

Note: If you’re adding a phone property, the value should follow the international standard E.164 format.


window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.login(data, callback);

// Example

window.Tawk_API.login({
  hash : '',    // required
  userId : '1234',            // required
  name : 'Name'
  email : 'email@email.com',
  phone : '09123456789'
}, function(error) {
  // do something if error
});

// Example property name as object

window.Tawk_API.login({
  hash : '',    // required
  userId : '1234',            // required
  name : {
    first : 'First',
    last : 'Last'
  }
}, function(error) {
  // do something if error
});

// Here is an example of login with custom attributes

window.Tawk_API.login({
  hash : '',    // required
  userId : '1234',            // required
  id : 'A1234',
  store : 'Midvalley'
}, function(error) {
  // do something if error
});

logout

This function will logout a user logged in. It doesn’t require any properties the server-side will handle if there’s a user logged in.

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.logout(callback);

// Example

window.Tawk_API.logout(
  function(error){
    // do something if error
  }
);

onLoad

Callback function invoked right after the widget is rendered. This callback is not supported in pop out chat window.

window.Tawk_API = window.Tawk_API || {};
window.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.

window.Tawk_API = window.Tawk_API || {};
window.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.

window.Tawk_API = window.Tawk_API || {};
window.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.

window.Tawk_API = window.Tawk_API || {};
window.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.

window.Tawk_API = window.Tawk_API || {};
window.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.

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.onChatHidden = function(){
    //place your code here
};

onChatStarted

Callback function invoked when the widget is started.

window.Tawk_API = window.Tawk_API || {};
window.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.

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.onChatEnded = function(){
    //place your code here
};

onPrechatSubmit

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

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.onPrechatSubmit = function(data){
    //place your code here
};

onOfflineSubmit

Callback function invoked when the Offline form is 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.

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.onOfflineSubmit = function(data){
    //place your code here
};

onChatMessageVisitor

Callback function invoked when message is sent by the visitor. The message is passed to the callback. This callback is not supported in pop out chat window.

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.onChatMessageVisitor = function(message){
    //place your code here
};

onChatMessageAgent

Callback function invoked when message is sent by the agent. The message is passed to the callback. This callback is not supported in pop out chat window.

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.onChatMessageAgent = function(message){
    //place your code here
};

onChatMessageSystem

Callback function invoked when message is sent by the system. The message is passed to the callback. This callback is not supported in pop out chat window.

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.onChatMessageSystem = function(message){
    //place your code here
};

onAgentJoinChat

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

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.onAgentJoinChat = function(data){
    //place your code here
};

onAgentLeaveChat

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

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.onAgentLeaveChat = function(data){
    //place your code here
};

onChatSatisfaction

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

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.onChatSatisfaction = function(statisfaction){
    //place your code here
};

onVisitorNameChanged

Callback function invoked when the visitor manually changes his name. The visitorName is passed to the callback. This callback is not supported in pop out chat window.

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.onVisitorNameChanged = function(visitorName){
    //place your code here
};

onFileUpload

Callback function invoked when a file is uploaded. The link to the uploaded file is passed to the callback. This callback is not supported in pop out chat window.

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.onFileUpload = function(link){
    //place your code here
};

onTagsUpdated

Callback function invoked when a tag is updated.

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.onTagsUpdated = 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 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.

Note: If you’re adding a phone property, the value should follow the international standard E.164 format.

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.visitor = {
    name  : 'Name',
    email : 'email@email.com'
};

maximize();

Maximizes the chat widget.

window.Tawk_API.maximize();

//Example

window.Tawk_API.onLoad = function(){
    window.Tawk_API.maximize();
};

minimize();

Minimizes the chat widget.

window.Tawk_API.minimize();

//Example

window.Tawk_API.onLoad = function(){
    window.Tawk_API.minimize();
};

toggle();

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

window.Tawk_API.toggle();

//Example

window.Tawk_API.onLoad = function(){
    window.Tawk_API.toggle();
};

popup();

Opens the chat widget as a pop out.

window.Tawk_API.popup();

//Example

window.Tawk_API.onLoad = function(){
    window.Tawk_API.popup();
};

getWindowType();

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

window.Tawk_API.getWindowType();

//Example

window.Tawk_API.onLoad = function(){
    if(window.Tawk_API.getWindowType() === 'inline'){
        // do something if it's inline
    }else{
        // do something if it's embed
    }
};

showWidget();

Shows the chat widget.

window.Tawk_API.showWidget();

//Example

window.Tawk_API.onLoad = function(){
    window.Tawk_API.showWidget();
};

hideWidget();

Hides the chat widget.

window.Tawk_API.hideWidget();

//Example

window.Tawk_API.onLoad = function(){
    window.Tawk_API.hideWidget();
};

toggleVisibility();

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

window.Tawk_API.toggleVisibility();

//Example

window.Tawk_API.onLoad = function(){
    window.Tawk_API.toggleVisibility();
};

getStatus();

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

window.Tawk_API.getStatus();

//Example

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

window.Tawk_API.isChatMaximized();


//Example

window.Tawk_API.onLoad = function(){
    if(window.Tawk_API.isChatMaximized()){
        //do something if it's maximized
    }
};

isChatMinimized();

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

window.Tawk_API.isChatMinimized();

//Example

window.Tawk_API.onLoad = function(){
    if(window.Tawk_API.isChatMinimized()){
        // do something if it's minimized
    }
};

isChatHidden();

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

window.Tawk_API.isChatHidden();

//Example

Tawk_API.onLoad = function(){
    if(window.Tawk_API.isChatHidden()){
        // do something if chat widget is hidden
    }
};

isChatOngoing();

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

window.Tawk_API.isChatOngoing();

//Example

Tawk_API.onLoad = function(){
    if(window.Tawk_API.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.

window.Tawk_API.isVisitorEngaged();

//Example

window.Tawk_API.onLoad = function(){
    if(window.Tawk_API.isVisitorEngaged()){
        // do something if visitor is engaged in chat
    }
};

endChat();

Ends the current ongoing chat.

window.Tawk_API.endChat();

//Example

window.Tawk_API.onLoad = function(){
    window.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 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

Note: If you’re adding a phone property, the value should follow the international standard E.164 format.

window.Tawk_API.setAttributes(attributes, callback);

//Example

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


//Example for setting name and email

window.Tawk_API.onLoad = function(){
    window.Tawk_API.setAttributes({
        'name'  : 'Name',
        'email' : 'email@email.com',
        'hash'  : 'hash value'
    }, function(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

window.Tawk_API.addEvent(eventName, metadata, callback);

//Example

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

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

window.Tawk_API.addTags(tags, callback);

//Example

window.Tawk_API.onLoad = function(){
    window.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 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

window.Tawk_API.removeTags(tags, callback);

//Example

window.Tawk_API.onLoad = function(){
    window.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, the user’s email and your site’s API key.

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

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.visitor = {
    name  : 'Name',
    email : 'email@email.com',
    hash  : '<calculate-hash>'
};

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

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

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.

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.customStyle = {
    zIndex : Integer|String
};

//Example

window.Tawk_API = window.Tawk_API || {};
window.Tawk_API.customStyle = {
    zIndex : 1000
};

window.Tawk_API.customStyle = {
    zIndex : '1000'
};

window.Tawk_API.customStyle = {
    zIndex : '1000 !important'
};