Chat Widget V1

• Getting Started
• Chat Widget Methods
• Chat Widget Events
• Chat Widget Snipped Code Configuration
• Content Security Policy
• CSP Domain Description
• Chat Widget Scenario Best Practices Use 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

webchat.selfHostedApp.open()

Close chat widget

webchat.selfHostedApp.close()

Set context

The following information should be taken into account when setting the context of the chat widget:

• Does not support complex schema, it only currently supports the key value and the value type, which can only be a string or number.
• It is only passed to Talkdesk Studio when a conversation is first created.
• Calling this method to update an ongoing conversation cannot be synchronized to the conversation app context card.

webchat.setContextParam({ "var1": "value1", "var2": "value2", "var3": 100 })

Set the default value of Initial Screen form

When you enable the Initial Screen function in Admin, if you need to add some default values ​​to the form, the field name passed in can be seen in the admin chat touchpoint

webchat.setCustomFieldDefaultValues({ "field_email1": "[[email protected]](mailto:[email protected])","field_number1": "+1" })

Chat Widget Events

Initialization completed

webchat.init(configs).then(function() {
  // Some things you want to do after Chat JSSDK is initialized
})

When chat is opened

webchat.onOpen = function () {
  // Some things you want to do after chat is opened
}

When chat is closed

webchat.onClose = function () {
  // Some things you want to do after chat is closed
}

When the conversation starts

webchat.onConversationStart = function () {
  // Some things you want to do after the conversation start
}

Chat Widget Snippet Code Configuration

props configuration

configs configuration

configs.styles configuration

Customizing the widget launch:

Customizing the widget window:

Customizing the widget header:

Customizing the initial screen:

Customizing the conversation

Customizing the close conversation dialog for contacts

Content Security Policy (CSP)

When a website has a Content Security Policy (CSP) enabled, it restricts the types of content that can be loaded on the site. To ensure that chat functionalities run properly, specific sources must be whitelisted. Below is a description of the CSP configuration needed for Talkdesk regions, including td-us-1, td-eu-1, td-ca-1, and td-usfed-1, to ensure chat functions properly on the website.

CSP Domain Description

Below is the description of the purpose of CSP domains. Each of these domains 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

Default to Hide Chat Launch Icon, Use Customer's Website Button to Open Chat

When customers need to hide the minimized icon of TD chat and then use a button or link on their website to trigger the maximized TD chat, the following is an example of the integration code.

+<button onclick="webchat && webchat.selfHostedApp.open()">click to show chat</button>
+<button onclick="webchat && webchat.selfHostedApp.close()">click to hide chat</button>

+<a id="show-link">click to show chat</a>
+<a id="hide-link">click to hide chat</a>

+<!--custom js code to trigger td chat-->
+<script>
+  document.getElementById("show-link").onclick = function () {
+    webchat && (webchat.selfHostedApp.open())
+  }
+  document.getElementById("hide-link").onclick = function () {
+    webchat && (webchat.selfHostedApp.close())
+  }
+</script>

<!-- 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/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, 
          enableEmoji: true, 
          enableUserInput: true, 
          enableAttachments: true,
+         styles: {
+           // hidden lanuch chat icon
+           triggerButtonPositionBottom: "-65px",
+           triggerButtonPositionRight: "-65px",
+         },
        }
      );
    </script>
<!-- End of Talkdesk Code -->

Open Chat Widget Automatically on Page Load

The customer needs to automatically open TD chat every time the contact person visits the website. The following is an example of the integration 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/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.init(configs).then(function() {
+           webchat.selfHostedApp.open()
+         });
          /*
           * 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, enableEmoji: true, enableUserInput: true, enableAttachments: true }
      );
    </script>
<!-- End of Talkdesk Code -->

Show or Hide Attachments or Emojis in Chat

If the customer website integrates Chat and needs to turn off attachments or emoticon functions, you can modify these configuration items to turn them on and off.

<!-- 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/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,
+         enableEmoji: true, // if set the value is false then emoji disable
          enableUserInput: true, 
+         enableAttachments: true // if set the value is false then attachment disable
        }
      );
    </script>
<!-- End of Talkdesk Code -->

Manage Automatic Fullscreen Mode in Chat

If we enable the responsive layout when the screen width is lower than 600px or the height is lower than 620px, the chat widget will be resized to full screen, and if we disable the responsive layout, we’ll not set a full screen for the chat widget at any time.

<!-- 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/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,
          enableEmoji: true,
          enableUserInput: true, 
          enableAttachments: true,
+         enableResponsiveLayout: true // if the value is set to false, then responsive layout feature will be disable
        }
      );
    </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.

<!-- 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/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,
          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 -->

Pass Custom Context to TalkDesk Studio when Conversationstart

If the customer website has some values ​​that need to be passed to the conversation app, this can be achieved using the following integrated code in the context card on the right.

📘

Note

If you really need to display it in the Conversations app context card, you also need to set the mapping relationship in the ChatDesk studio context panel associated with Chat.Below is an example of setting a screenshot

Step 1:Click the 'add' button

Step 2: Add the context you need to Talkdesk Studio

Step 3: Select the context items you need

<!-- 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/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() {
+            // You can modify the object parameters and values ​​in the following methods
             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, enableEmoji: true, enableUserInput: true, enableAttachments: true }
      );
    </script>
<!-- End of Talkdesk Code -->

Create and Identify a Contact Automatically

Integrated customers can call the setContextParam method provided by our jssdk on their website to pass the contact person's phone number or email. It must be passed using the td_contact_person_identification field, which currently only supports email or phone number. 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/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({
+             // Here, the unique identifier of the contact person is passed to talkdesk. Currently, only phone numbers and email addresses are supported. Please choose one to pass.
+              "td_contact_person_identification": "[email protected]"
             })
           }
           // 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 -->

Set Default Values ​​for the Initial Screen Form

The field name is generated in the channel's chat touchpoint initial screen form:

If default values are set for all fields, the chat will automatically skip the initial screen form stage and be automatically passed to the TalkDesk system when the conversation starts.

<!-- 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/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);
+         // 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.setCustomFieldDefaultValues({
+           "field_email1": "[email protected]",
+           "field_number1": "+1",
+         });
          /*
           * 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, enableEmoji: true, enableUserInput: true, enableAttachments: true }
      );
    </script>
<!-- End of Talkdesk Code -->