Chat Widget V2

• Getting Started
• Chat Widget Methods
• Chat Widget Events
• Chat Widget Snippet Code Configuration
• Chat Widget Theme Configuration
• Content Security Policy
• CSP Domain Description
• Chat Widget Scenario Best Practice Cases

Getting Started

Chat Widget is a JSSDK (hereafter referred to as Chat widget) that allows embedding into your own website, it comes in handy whenever contacts want to contact you, more detailed configuration and usage documents are here. This document mainly focuses on JSSDK-related content.

Chat Widget Methods

Open chat widget

The open method is used for opening the chat widget by hitting the icon.

webchat.open()

The open method is used for opening the chat widget by hitting the icon.

Close chat widget
The close method is used for minimizing the chat widget by hitting the minimize icon in the chat box header, it needs to be invoked after the initialization of the chat widget.

webchat.close()

Set context
The setContextParam method is used for transmitting customized key-value context to TD internal systems such as Studio Flow, for example. We can transmit the customer’s using language or address to the agent. The customized context will be displayed in the Context tab of Conversation through Studio.

🚧

The setContextParam can be used to set default values for the Initial screen form in chat-widget. If we set default values for all the form controls of Initial screen, the Initial screen will be skipped before the conversation starts.

webchat.setContextParam({ 
  "var1": "dummy value for var1", 
  "var2": "dummy value var2",
  "field_name1": "dummy name",
  "field_email1": "[email protected]"
  ...
})

Chat Widget Events

Initialization completed
This method is used for doing something after chat widget is initialized. It’s an asynchronous function and receives the customized configuration of chat widget as arguments.

webchat.init(configs).then(function () {
  // your own business logic after chat widget initialized
})

When Chat is opened
The onOpenWebchat method is used for doing something after the chat widget is opened. It receives a callback as its argument to execute your customized logic.

const doSomething = () => {
  //your own business logic when chat widget is opened
}

webchat.onOpenWebchat(doSomething)

When chat is closed
The onCloseWebchat method is used for doing something after the chat widget is closed. It receives a callback as its argument to execute your customized logic.

const doSomething = () => {
  //your own business logic when chat widget is closed
}

webchat.onCloseWebchat(doSomething)

When the conversation starts
The onConversationStart method is used for doing something after the chat conversation starts. It receives a callback as its argument to execute your customized logic.

const doSomething = () => {
  //your own business logic when conversation starts
}

webchat.onConversationStart(doSomething)

Chat Widget Snippet Code Configuration

The snippet code is embedded in the customer’s website and can be customized according to the configuration you transmit.

<!-- Start of Talkdesk Code -->
    <script>
      var webchat;
      (function(window, document, node, props, configs) {
        if (window.TalkdeskChatSDK) {
          console.error("TalkdeskChatSDK already included");
          return;
        }
        var divContainer = document.createElement("div");
        divContainer.id = node;
        document.body.appendChild(divContainer);
        var src = "https://talkdeskchatsdk.talkdeskapp.com/v2/talkdeskchatsdk.js";
        var script = document.createElement("script");
        var firstScriptTag = document.getElementsByTagName("script")[0];
        script.type = "text/javascript";
        script.charset = "UTF-8";
        script.id = "tdwebchatscript";
        script.src = src;
        script.async = true;
        firstScriptTag.parentNode.insertBefore(script, firstScriptTag);
        script.onload = function() {
          webchat = TalkdeskChatSDK(node, props);
          webchat.init(configs);
        };
      })(
        window,
        document,
        "tdWebchat",
        { touchpointId: "<customer touchpointId>", accountId: "", region: "<customer td region>" },
        { enableEmoji: true, enableAttachments: true, enableValidation: true, enableResponsiveLayout: true, styles: {} }
      );
    </script>
<!-- End of Talkdesk Code -->

props configuration

configs configuration

Chat Widget Theme Configuration

The chat widget supports customizing themes to have a better UX for Customers.

Customizing the chat widget launcher

Launcher

Customizing the widget window

Widget window

Customizing the initial screen

Welcome message

Custom message

Custom field

Custom dropdown

Custom button

Customizing the conversation

Conversation

Bot

Avatar

Button

Start chat button

Quick reply

Customizing the close conversation dialog

Dialog

Content Security Policy (CSP)

Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks, including Cross-Site Scripting (XSS) and data injection attacks. These attacks are used for everything, from data theft to site defacement or malware distribution.

Most customers use CSP to protect their websites from attack, and they will set strict rules for the third-party libs. In order to run the chat widget steadily, we need to provide a whitelist for the customer to avoid being intercepted.

Usually, the CSP tool will detect the src field in the script, frame, or the elements that have the attribute to decide whether to intercept.

CSP Domain Description

Below is the description of the domains in CSP rules. Each domain plays a crucial role in enabling chat services by specifying trusted sources from which content can be loaded, ensuring both functionality and security for users in their respective regions.

Chat Widget Scenario Best Practice Cases

1. Hide chat launcher icon and open chat-widget
In cases where you prefer not to display the default chat launcher icon and instead want to open the chat widget through a custom element on your web page like an icon, link, or menu, you can achieve this by following these steps:

1. Hide the Chat Launcher Icon
   Utilize the SDK's configuration options to ensure the default launcher icon is hidden from view.
2. Trigger the Chat Widget Using the webchat.open() API
   Implement a custom trigger (e.g., button, menu item, or link) in your web application that calls the webchat.open() method to open the chat widget programmatically.

Example of the integrated code:

+<button onclick="webchat && webchat.open()">your button</button>
+<a href="javasciprt:void(0)" onclick="webchat && webchat.open()">your link</a>

<!-- Start of Talkdesk Code -->
    <script>
      var webchat;
      (function(window, document, node, props, configs) {
        if (window.TalkdeskChatSDK) {
          console.error("TalkdeskChatSDK already included");
          return;
        }
        var divContainer = document.createElement("div");
        divContainer.id = node;
        document.body.appendChild(divContainer);
        var src = "https://talkdeskchatsdk.talkdeskapp.com/v2/talkdeskchatsdk.js";
        var script = document.createElement("script");
        var firstScriptTag = document.getElementsByTagName("script")[0];
        script.type = "text/javascript";
        script.charset = "UTF-8";
        script.id = "tdwebchatscript";
        script.src = src;
        script.async = true;
        firstScriptTag.parentNode.insertBefore(script, firstScriptTag);
        script.onload = function() {
          webchat = TalkdeskChatSDK(node, props);
          webchat.init(configs);
        };
      })(
        window,
        document,
        "tdWebchat",
        { touchpointId: "<customer touchpointId>", accountId: "", region: "<customer td region>" },
        { 
          enableValidation: false, 
          enableEmoji: true, 
          enableUserInput: true, 
          enableAttachments: true,
+         styles: {
+           // hidden lanuch chat icon
+           triggerButtonPositionBottom: "-65px",
+           triggerButtonPositionRight: "-65px",
+         },
        }
      );
    </script>
<!-- End of Talkdesk Code -->

2. Automatically open chat widget
The customer needs to automatically open TD chat every time the contact person visits the website. The following is the integration code.

Example of the integrated code:

<!-- Start of Talkdesk Code -->
    <script>
      var webchat;
      (function(window, document, node, props, configs) {
        if (window.TalkdeskChatSDK) {
          console.error("TalkdeskChatSDK already included");
          return;
        }
        var divContainer = document.createElement("div");
        divContainer.id = node;
        document.body.appendChild(divContainer);
        var src = "https://talkdeskchatsdk.talkdeskapp.com/v2/talkdeskchatsdk.js";
        var script = document.createElement("script");
        var firstScriptTag = document.getElementsByTagName("script")[0];
        script.type = "text/javascript";
        script.charset = "UTF-8";
        script.id = "tdwebchatscript";
        script.src = src;
        script.async = true;
        firstScriptTag.parentNode.insertBefore(script, firstScriptTag);
        script.onload = function() {
          webchat = TalkdeskChatSDK(node, props);
          webchat.init(configs);
        };
      })(
        window,
        document,
        "tdWebchat",
        { 
          touchpointId: "<customer touchpointId>", 
          accountId: "", 
          region: "<customer td region>", 
+         autoOpen: true
        },
        { enableValidation: false, enableEmoji: true, enableUserInput: true, enableAttachments: true }
      );
    </script>
<!-- End of Talkdesk Code -->

3. Show/hide attachments or emojis
The attachments and emojis are controlled by transmitting the enableAttachments and enableEmoji fields in the configs of snippet code.

Example of the integrated code:

<!-- Start of Talkdesk Code -->
    <script>
      var webchat;
      (function(window, document, node, props, configs) {
        if (window.TalkdeskChatSDK) {
          console.error("TalkdeskChatSDK already included");
          return;
        }
        var divContainer = document.createElement("div");
        divContainer.id = node;
        document.body.appendChild(divContainer);
        var src = "https://talkdeskchatsdk.talkdeskapp.com/v2/talkdeskchatsdk.js";
        var script = document.createElement("script");
        var firstScriptTag = document.getElementsByTagName("script")[0];
        script.type = "text/javascript";
        script.charset = "UTF-8";
        script.id = "tdwebchatscript";
        script.src = src;
        script.async = true;
        firstScriptTag.parentNode.insertBefore(script, firstScriptTag);
        script.onload = function() {
          webchat = TalkdeskChatSDK(node, props);
          webchat.init(configs);
          /*
           * Send custom data from your website to TalkDesk!
           * If you would like to do it, you need to remove the following commented code and
           * modify the webchat.setContextParam parameters to pass in the data you need.
           */
           /*function setContext() {
             webchat.setContextParam({ "var1": "value1", "var2": "value2", "var3": 100 })
           }
           // Send data when the chat conversation is initiated
           webchat.onConversationStart = function() {
             setContext()
           }
           // Send data when the chat widget is open
           webchat.onOpenWebchat = function() {
             setContext()
           }*/
        };
      })(
        window,
        document,
        "tdWebchat",
        { touchpointId: "<customer touchpointId>", accountId: "", region: "<customer td region>" },
        { 
          enableValidation: false,
          enableUserInput: true, 
+         enableEmoji: true,
+         enableAttachments: true
        }
      );
    </script>
<!-- End of Talkdesk Code -->

4. Automatically fullscreen chat widget
If the screen’s width is lower than 600px or the height is lower than 620px, the chat widget will be resized to full-screen while enabling the enableResponsiveLayout, but we’ll not set it to full-screen for the chat widget at any time if enableResponsiveLayout is disabled.

Example of the integrated code:

<!-- Start of Talkdesk Code -->
    <script>
      var webchat;
      (function(window, document, node, props, configs) {
        if (window.TalkdeskChatSDK) {
          console.error("TalkdeskChatSDK already included");
          return;
        }
        var divContainer = document.createElement("div");
        divContainer.id = node;
        document.body.appendChild(divContainer);
        var src = "https://talkdeskchatsdk.talkdeskapp.com/v2/talkdeskchatsdk.js";
        var script = document.createElement("script");
        var firstScriptTag = document.getElementsByTagName("script")[0];
        script.type = "text/javascript";
        script.charset = "UTF-8";
        script.id = "tdwebchatscript";
        script.src = src;
        script.async = true;
        firstScriptTag.parentNode.insertBefore(script, firstScriptTag);
        script.onload = function() {
          webchat = TalkdeskChatSDK(node, props);
          webchat.init(configs);
        };
      })(
        window,
        document,
        "tdWebchat",
        { touchpointId: "<customer touchpointId>", accountId: "", region: "<customer td region>" },
        { 
          enableValidation: false,
          enableEmoji: true,
          enableUserInput: true, 
          enableAttachments: true,
+         enableResponsiveLayout: true
        }
      );
    </script>
<!-- End of Talkdesk Code -->

It may not be good to simply disable the full-screen capability. For example, the automatic full-screen capability is still needed on some mobile devices, but you can not use it on a PC. The following is an example.

Example of the integrated code:

<!-- Start of Talkdesk Code -->
    <script>
      var webchat;
      (function(window, document, node, props, configs) {
        if (window.TalkdeskChatSDK) {
          console.error("TalkdeskChatSDK already included");
          return;
        }
        var divContainer = document.createElement("div");
        divContainer.id = node;
        document.body.appendChild(divContainer);
        var src = "https://talkdeskchatsdk.talkdeskapp.com/v2/talkdeskchatsdk.js";
        var script = document.createElement("script");
        var firstScriptTag = document.getElementsByTagName("script")[0];
        script.type = "text/javascript";
        script.charset = "UTF-8";
        script.id = "tdwebchatscript";
        script.src = src;
        script.async = true;
        firstScriptTag.parentNode.insertBefore(script, firstScriptTag);
        script.onload = function() {
          webchat = TalkdeskChatSDK(node, props);
          webchat.init(configs);
        };
      })(
        window,
        document,
        "tdWebchat",
        { touchpointId: "<customer touchpointId>", accountId: "", region: "<customer td region>" },
        { 
          enableValidation: false,
          enableEmoji: true,
          enableUserInput: true, 
          enableAttachments: true,
+         enableResponsiveLayout: |Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(window.navigator.userAgent),
        }
      );
    </script>
<!-- End of Talkdesk Code -->

5. Transmit custom context to studio flow
We can use the setContextParam method to transmit some useful information to the Conversations App. The method will collect the data and then transmit it to Studio flow, Studio will send the data to the Context card in the Conversations App according to the configuration in the Studio context. Here are the steps on how to display the context in the context card of the Conversations App.

Example of the integrated code:

<!-- Start of Talkdesk Code -->
    <script>
      var webchat;
      (function(window, document, node, props, configs) {
        if (window.TalkdeskChatSDK) {
          console.error("TalkdeskChatSDK already included");
          return;
        }
        var divContainer = document.createElement("div");
        divContainer.id = node;
        document.body.appendChild(divContainer);
        var src = "https://talkdeskchatsdk.talkdeskapp.com/v2/talkdeskchatsdk.js";
        var script = document.createElement("script");
        var firstScriptTag = document.getElementsByTagName("script")[0];
        script.type = "text/javascript";
        script.charset = "UTF-8";
        script.id = "tdwebchatscript";
        script.src = src;
        script.async = true;
        firstScriptTag.parentNode.insertBefore(script, firstScriptTag);
        script.onload = function() {
          webchat = TalkdeskChatSDK(node, props);
          webchat.init(configs);       
+         webchat.setContextParam({ 
+           "contact_email": "[email protected]", 
+           "contact_name": "dummy",
+         })
       };
      })(
        window,
        document,
        "tdWebchat",
        { touchpointId: "<customer touchpointId>", accountId: "", region: "<customer td region>" },
        { enableValidation: false, enableEmoji: true, enableUserInput: true, enableAttachments: true }
      );
    </script>
<!-- End of Talkdesk Code -->

Step 1: Add a new argument in the Initial step component in studio flow, you can add the context transmitted by the customer.

Step 2: Select the new context you already created in step 1 and save it.

Step 3: Go to the Conversations App to check the data in the Context card at the right hand of the page.

7. Set pre-filled values ​​for the fields on the Initial screen

The Chat Widget JavaScript SDK allows you to dynamically set pre-filled values for the fields on the initial form. This functionality is useful in scenarios where contact person information is already stored in an external system. For instance, if your system maintains such as the contact person's name and email address information, these can be pre-fill into the chat widget fields.

📘

If pre-filled values are provided for ALL fields on the initial form, the data will be automatically submitted to the TalkDesk system when the chat begins.

In this case, the chat widget will bypass the initial form stage, allowing the conversation to start immediately without user input.

Example of the integrated code

<!-- Start of Talkdesk Code -->
    <script>
      var webchat;
      (function(window, document, node, props, configs) {
        if (window.TalkdeskChatSDK) {
          console.error("TalkdeskChatSDK already included");
          return;
        }
        var divContainer = document.createElement("div");
        divContainer.id = node;
        document.body.appendChild(divContainer);
        var src = "https://talkdeskchatsdk.talkdeskapp.com/v2/talkdeskchatsdk.js";
        var script = document.createElement("script");
        var firstScriptTag = document.getElementsByTagName("script")[0];
        script.type = "text/javascript";
        script.charset = "UTF-8";
        script.id = "tdwebchatscript";
        script.src = src;
        script.async = true;
        firstScriptTag.parentNode.insertBefore(script, firstScriptTag);
        script.onload = function() {
          webchat = TalkdeskChatSDK(node, props);
          webchat.init(configs);       
          /*
           * Send custom data from your website to TalkDesk!
           * If you would like to do it, you need to remove the following commented code and
           * modify the webchat.setContextParam parameters to pass in the data you need.
           */
-          /*function setContext() {
+          function setContext() {
-            webchat.setContextParam({ "var1": "value1", "var2": "value2", "var3": 100 })
+            // Note: Set the default value of the Initial screen form here. If default values ​​are set for all fields, Talkdesk Chat will automatically skip the Initial screen stage and go directly to the conversation ui.
+            webchat.setContextParam({
+              "field_email1": "[email protected]",
+              "field_number1": "+1",
+            })
           }
           // Send data when the chat conversation is initiated
           webchat.onConversationStart = function() {
             setContext()
           }
           // Send data when the chat widget is open
           webchat.onOpenWebchat = function() {
             setContext()
-          }*/
+          }
        };
      })(
        window,
        document,
        "tdWebchat",
        { touchpointId: "<customer touchpointId>", accountId: "", region: "<customer td region>" },
        { enableValidation: false, enableEmoji: true, enableUserInput: true, enableAttachments: true }
      );
    </script>
<!-- End of Talkdesk Code -->

8. Support internationalization and layout

The chat widget allows for multi-language support by configuring the languageCode field. By setting this field, customers can specify the language of the chat interface using standard international language codes. For instance: en-US for English (United States), pt-PT for Portuguese (Portugal).

The default layout direction of the chat widget is Left-to-Right (LTR). It is not necessary to manually set this value for LTR languages, as it is automatically configured based on the language code provided.

For languages that require a Right-to-Left (RTL) layout, such as Arabic, the layout direction is also set automatically. When a language code corresponding to an RTL language is specified (e.g., ar-SA or ar-EG), the chat widget will adjust its layout direction accordingly, providing a seamless user experience for RTL language speakers.

📘

When the languageCode field is set to empty, it will automatically set the browser's language.

If automatic identification or pass-through configuration parameters are not supported, it will be fall back to en-US

<!-- Start of Talkdesk Code -->
    <script>
      var webchat;
      (function(window, document, node, props, configs) {
        if (window.TalkdeskChatSDK) {
          console.error("TalkdeskChatSDK already included");
          return;
        }
        var divContainer = document.createElement("div");
        divContainer.id = node;
        document.body.appendChild(divContainer);
        var src = "https://talkdeskchatsdk.talkdeskapp.com/v2/talkdeskchatsdk.js";
        var script = document.createElement("script");
        var firstScriptTag = document.getElementsByTagName("script")[0];
        script.type = "text/javascript";
        script.charset = "UTF-8";
        script.id = "tdwebchatscript";
        script.src = src;
        script.async = true;
        firstScriptTag.parentNode.insertBefore(script, firstScriptTag);
        script.onload = function() {
          webchat = TalkdeskChatSDK(node, props);
          webchat.init(configs);
        };
      })(
        window,
        document,
        "tdWebchat",
        { touchpointId: "<customer touchpointId>", accountId: "", region: "<customer td region>" },
        { 
          enableValidation: false,
          enableEmoji: true,
          enableUserInput: true, 
          enableAttachments: true,
+         languageCode: "pt-PT", // Notes support the languageCodes: en-US pt-PT pt-BR es-ES de-DE fr-FR it-IT ar-SA ar-EG
        }
      );
    </script>
<!-- End of Talkdesk Code -->

9. Drag and move chat launcher

The "Drag and Move Chat Launcher" feature enhances the user experience by addressing the need for flexibility and unobstructed access to application information on PC and mobile devices. The ability to move the chat widget, especially within the mobile application for the following reasons:

Customizable Positioning: Users want the flexibility to reposition the chat launcher to a location on their screen that best suits their preferences and usage patterns. This ensures that the chat widget does not interfere with the personal viewing experience.

Unobstructed Access: The current fixed position of the chat widget has been reported to block important application information, which can hinder the user experience by obscuring critical content. Allowing users to move the chat widget ensures that all essential information remains visible and accessible, improving overall usability and satisfaction.

📘

The enablePointMoveTriggerButton is used to turn on the drag and move of the chat launcher, and the value of this field is false by default.

Example of the integrated code:

<!-- Start of Talkdesk Code -->
    <script>
      var webchat;
      (function(window, document, node, props, configs) {
        if (window.TalkdeskChatSDK) {
          console.error("TalkdeskChatSDK already included");
          return;
        }
        var divContainer = document.createElement("div");
        divContainer.id = node;
        document.body.appendChild(divContainer);
        var src = "https://talkdeskchatsdk.talkdeskapp.com/v2/talkdeskchatsdk.js";
        var script = document.createElement("script");
        var firstScriptTag = document.getElementsByTagName("script")[0];
        script.type = "text/javascript";
        script.charset = "UTF-8";
        script.id = "tdwebchatscript";
        script.src = src;
        script.async = true;
        firstScriptTag.parentNode.insertBefore(script, firstScriptTag);
        script.onload = function() {
          webchat = TalkdeskChatSDK(node, props);
          webchat.init(configs);
        };
      })(
        window,
        document,
        "tdWebchat",
        { touchpointId: "<customer touchpointId>", accountId: "", region: "<customer td region>" },
        { 
          enableValidation: false,
          enableEmoji: true,
          enableUserInput: true, 
+         enablePointMoveTriggerButton: true
        }
      );
    </script>
<!-- End of Talkdesk Code -->

If you only wish to drag and move the chat launcher on mobile, you can specify the value of this field. The following is an example of the integrated code:

<!-- Start of Talkdesk Code -->
    <script>
      var webchat;
      (function(window, document, node, props, configs) {
        if (window.TalkdeskChatSDK) {
          console.error("TalkdeskChatSDK already included");
          return;
        }
        var divContainer = document.createElement("div");
        divContainer.id = node;
        document.body.appendChild(divContainer);
        var src = "https://talkdeskchatsdk.talkdeskapp.com/v2/talkdeskchatsdk.js";
        var script = document.createElement("script");
        var firstScriptTag = document.getElementsByTagName("script")[0];
        script.type = "text/javascript";
        script.charset = "UTF-8";
        script.id = "tdwebchatscript";
        script.src = src;
        script.async = true;
        firstScriptTag.parentNode.insertBefore(script, firstScriptTag);
        script.onload = function() {
          webchat = TalkdeskChatSDK(node, props);
          webchat.init(configs);
        };
      })(
        window,
        document,
        "tdWebchat",
        { touchpointId: "<customer touchpointId>", accountId: "", region: "<customer td region>" },
        { 
          enableValidation: false,
          enableEmoji: true,
          enableUserInput: true, 
+         enablePointMoveTriggerButton: |Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(window.navigator.userAgent)
        }
      );
    </script>
<!-- End of Talkdesk Code -->