How can we help?

This article serves as a comprehensive guide on setting up and integrating the chat widget into your website, thus providing your customers with the option to contact your services and agents through chat.

Follow the steps detailed in this article to use the chat channel to its full potential. Add value to your website by seamlessly setting up and integrating the chat widget, ensuring its availability to customers.

For easier navigation, please use the index listing below:

• Creating a Chat Touchpoint
• Chat App
• Chat Touchpoint
  • • Touchpoint Tab
    • Appearance Tab
    • Settings Tab
• Chat Widget Integration
  • • Widget integration via iframe (recommended option)
    • Widget Integration via script
• Chat Widget Customization
• Context Variables
  • • Context Variables Received from the Initial Screen
    • Context Variables Received from the Website
    • Possible Applications for Context Variables
• Visitor Identification
  • • Creating and Identifying a Contact Manually
    • Creating and Identifying a Contact Automatically
• Additional Resources

 

Creating a Chat Touchpoint

To create a new “Chat touchpoint”, go to “Admin” > “Channels” > “Chat”, and click the Create touchpoint button.

This will open a pop-up window, asking you to provide the domain (mandatory) and the friendly name (mandatory) of the new chat touchpoint. Click Create.

The new chat touchpoint will now be visible on the list and will be inactive by default. Click the touchpoint’s domain to complete its configuration.

Locate the “Touchpoint” section and click Edit. 

You can now select the Studio flow that should be assigned to the new chat touchpoint. Click Save to return to the configuration page.

Choose the Appearance tab, and click Edit. Here, you have the option to customize the chat widget’s content, such as:

• Welcome message.
• Fields (customer information).
• Dropdowns (e.g. language selection).
• Messages (valuable information).
• Actions buttons (e.g. “Start chat”).

Integrate the chat widget in the desired pages of your website. This can be done via iframe (recommended option) or via script. Check the “Widget Integration” section for more details.

After integrating the chat widget on your website, go to “Admin” > “Channels” > “Chat” > Touchpoint.

In the Touchpoint tab, click Edit.

You can now activate the chat touchpoint by sliding the “Status” toggle. Save your progress.

Reload your website, and you should be able to see the chat widget in the web pages where it was integrated.

While configuring the chat touchpoint, please have the following guidelines in mind:

 

Domain

• Protocols and ‘www.’

The system differentiates between the two available protocols ("http:" and "https:") and does not differentiate between domains that include ‘www.’ and domains that do not include 'www.’. 

Note: It’s possible to remove the protocol information, and it will work for all combinations.

 

• Subdomains are supported.
• Subdirectories are not supported.

 

Firewall Exceptions

When a chat conversation is initiated, some URLs are called, and that need to make it through the firewall. Therefore, add the following URLs as firewall exceptions:

• https://api.talkdeskapp.com
• https://talkdeskchatsdk.talkdeskapp.com
• https://sessions.bugsnag.com
• wss://tsock.us1.twilio.com/v3/wsconnect
• https://prd-cdn-talkdesk.talkdesk.com
• https://cdn.jsdelivr.net

CSP security policy

If your website uses CSP security policy, whitelist these domains:

• https://mcs.us1.twilio.com
• wss://tsock.us1.twilio.com
• https://api.talkdeskapp.com
• https://talkdeskchatsdk.talkdeskapp.com

OneTrust security

If your website uses OneTrust, please note that, as part of its functionality, OneTrust utilizes the OtAutoBlock.js script to block suspicious behaviors, including reading and writing cookies from third-party sources such as Talkdesk Chat. Consequently, it can be blocked from loading, and, therefore, the chat launcher might not be displayed on the website. 

We recommend adding Talkdesk Chat to the trusted cookie settings. In order to do so:

• Log into your OneTrust account.
• Navigate to the cookie settings section and find the cookies associated with the Talkdesk Chat Widget and change their categorization to "Strictly Necessary";
• Depending on your consent model, you might need to update the settings of your consent banner to make sure users can provide consent for the cookies associated with Talkdesk Chat Widget.
• Once you’ve made these changes, test your website to make sure the chat widget loads as expected.

 

Chat App

Access Workspace and go to “Admin” > Channels. On the “Channels list” tab, you will find the “Chat” channel. Enter it to configure all chat touchpoints.

• Channels list: The channels available in your account. Select Chat to configure the channel’s touchpoints.
• Global settings: Settings applicable to one or more channels. E.g. the definition of the occupancy weight of each conversation for each channel.
• Templates: Create pre-written messages to help agents be more efficient.
• Chat channel: To configure this channel, click the Chat section within the “Channels” application.
• Number of touchpoints: This label indicates the number of touchpoints that were already configured for chat.

Use the Create new touchpoint button to create a new touchpoint. Once clicked, it will request the website domain and a friendly name for the touchpoint.

By clicking the “More options” button (...), you will be able to:

• Edit the chat touchpoint.
• Edit the chat appearance.
• Duplicate the appearance configurations to a new touchpoint (you will be asked for the domain and friendly name).
• Activate or deactivate the touchpoint.
• Delete the touchpoint (only possible if the chat is deactivated first. Note: Keep in mind that you also have to remove the widget code from the website).

 

Chat Touchpoint

For each chat touchpoint, there are three tabs: 

• “Touchpoint”
• “Appearance”
• “Setting”

Once you open a chat touchpoint, you are forwarded to the “Touchpoint” tab in view mode.

• “Touchpoint”: In this tab, you can set the domain of your website, assign a Studio flow, and copy the widget code to add it to your website. Note: The code snippet is only available in the view mode.
• “Appearance”: In this tab, you will be able to set up the functionality and behavior of the chat widget.
• “Settings”: In this tab, you will be able to configure the conversation preview permission in the Inbox app based on touchpoints and roles.

To switch the selected tab from view mode to edit mode, click the “Edit” button.

 

Touchpoint Tab

When entering the Touchpoint tab, you will be in view mode. In order to switch to the edit mode, click the Edit button to start configuring your chat touchpoint.

Use “Domain” to add the website URL where you want the widget to appear (check the available guidelines here). On the “Friendly name” field, provide a friendly name for the touchpoint, meaning that this will be the name shown to the agents.

Next, select the Studio flow to be assigned to the touchpoint, from the dropdown menu.

When configuring the chat for the first time, you can open the Configure a Studio flow link that will forward you to Studio so that you can create a Studio flow.

 

Note: You can switch the assigned Studio flow as often as needed, without having to change the code snippet on your website.

 

Slide the “Status” toggle to activate or deactivate the chat touchpoint. Save your progress.

 

: Once the widget code is added to the website, the chat widget will appear for every website visitor. 

 

: When deactivated, the chat widget will disappear from the website. Ongoing conversations will not be lost, but the visitor will not be able to start another conversation.

Note: The Save button will only be enabled once you add the domain and select a Studio flow.

After saving your configurations, you will return to view mode, where you will be able to see the applied configuration and the widget code that must be added to your website.

On the “Domain Information”, you can see the domain, the domain’s friendly name, and the assigned Studio flow.

After saving the touchpoint configurations, the widget code will be generated. Check this section for details on how to add the widget code to your website.

 

Note: The widget code section is only shown in the view mode.

 

Appearance Tab

When entering the “Appearance” tab, you will be in view mode. In order to switch to the edit mode, click the Edit button to start configuring your chat appearance.

• “General settings”: In this section, you can enable, disable, and configure the chat widget’s general settings.
• “Initial screen”: Here, you can enable or disable the initial screen and change its configuration.
• “Chat”: Add static messages that will be shown when the visitor is on the chat widget. If the initial screen is enabled, these messages will be shown after the visitor clicks on the button to start the chat conversation.
• “Preview style”: Preview of the chat widget screens. 

 

General Settings

When expanding the “General settings” tab, you will be able to configure its features.

Use the “Close conversation button” toggle to enable or disable visitors from closing the chat conversation.

After saving your configurations, you will return to view mode, where you will be able to see the applied configurations and which content will be shown in the chat widget. A status label indicates if the “Close conversation” option is enabled or not.

 

Initial Screen 

When expanding the “Initial screen” tab, you will be able to enable and configure its components.

Use the “Show/Hide initial screen” toggle to enable or disable the chat widget’s initial screen.

 

Note: The “Preview style” will update every time you perform a change to its components.

 

Add a “Welcome message” to the top of the chat widget to welcome your visitors. It can be composed of a title of up to 20 characters, and/or a text of up to 120 characters.

Then, you can create a pre-conversation form to get information from the visitor that can be used for routing purposes or to provide additional context to your agents.

Note that by default, there is a custom message, a custom field, a custom dropdown, and a custom button. These default components cannot be removed, but they will only be shown if you configure them.

You can use the + Add field button to add another custom component to the initial screen, according to the type you select: 

• “Button”
• “Dropdown”
• “Field”
•  “Message”

The “Custom button” adds a button (which you can label) to trigger an action. Currently, there is only one trigger option: “Start the chat”.

 

Note: Enable “Route conversation immediately after the user clicks this button”, if you would like Studio flow to be triggered as soon as the user clicks the button. If disabled, the user needs to send a message to trigger the Studio flow.

With the “Custom dropdown”, you can add a customized dropdown menu to the initial screen.

In the “Custom field”, you will add an input field to the initial screen, allowing the visitor to input information. You can add the label of the field in the text box, and then map it with the value you are collecting.

 

Note: As an example, if you want to ask for the visitor’s email address, type “Email” as the custom field’s name and select the “Contact email” option from the dropdown. In case you want to ask for a different type of information (e.g. order number) you can define the custom field’s value as “Custom option”.

The option to add a “Custom message” will add a message to the initial screen. By enabling the “Chat bubble” toggle, the message will be shown inside a chat bubble.

Deleting a field via the corresponding icon will remove that custom component from the initial screen.

 

Note: The default components cannot be deleted and, therefore, you need to delete their configuration in order to hide them from the initial screen. 

 

The “Required” toggle sets which fields are optional or mandatory before the visitor proceeds to the chat screen. Each component has a drag-and-drop tool that will allow you to change the presentation order of the components on the initial screen.

After saving your configurations, you will return to view mode and see the applied configuration and which content will be shown in the chat widget.

You will see a status label indicating if the initial screen is enabled or not, as well as a preview of your configuration. 

For each custom field or custom dropdown, a “Studio Argument” value will be generated. Each argument can be mapped to the “Incoming Message” component of the touchpoint’s Studio flow to provide context to agents or routing purposes.

 

Chat Screen

When expanding the “Chat” tab, you will be able to configure the chat screen.

If the initial screen is enabled, the chat screen is shown when the visitor clicks the Start the chat button. If there is no initial screen, the chat screen will be shown as soon as the visitor opens the chat widget.

In “Messages”, you can add static messages that will appear once the visitor is on the chat screen.

By default, there is one input box to add a message, but it will only be shown if you configure it. You can add as many messages as you want by clicking on the Add another message button.

 

Note: All messages will be presented in a chat bubble.

 

Press the “Delete” icon to avoid messages from appearing on the chat screen.

Each message has a drag-and-drop tool that will allow you to change the presentation order of the messages on the chat screen.

After saving your configurations, you will return to view mode, where you will be able to see the applied configuration and which content will be shown in the chat widget.

 

Settings Tab

In the “Settings” tab, you can configure settings at the touchpoint level, as well as overview the current configuration of the available settings. Click the desired touchpoint’s Edit button to configure the settings.

 

Conversation Preview

With the “Conversation Preview” option, you have the ability to grant or restrict certain roles from previewing chat conversations directly from the “Inbox” app.

• Allow previews: Toggle to enable or disable the conversation preview. When enabled, all the conversations of this touchpoint will be able to be previewed by authorized users.
• Authorized roles: When the “Allow previews” option is enabled, you can select the roles that can preview the touchpoint’s conversations.

 

Chat Widget Integration

Widget integration via iframe (recommended option)

To integrate a chat widget in your website via iframe, take the following steps: 

 

Step 1: Create an HTML file containing the chat widget code

Create an HTML file named chat-iframe.html containing the code snippet below:

In the highlighted line, the values of touchpointId and region need to be replaced by the correct ones.

The touchpointId corresponds to the chat touchpoint’s ID, and the region corresponds to the region where your account is hosted.

Both values can be found on the touchpoint configuration page (in view mode):

• Go to “Admin” > “Channels” > “Chat” > “Touchpoint”.
• In the “Touchpoint” tab in view mode, locate the widget code section.
• In the widget code, locate line 45, and there you will find the values of touchpointID and region you need to replace on the HTML file you created previously.

Alternatively, you can find the value for touchpointId and region in the URL bar of the web browser while visiting the touchpoint configuration page:

• https://youraccount.mytalkdesk.DOMAINEXTENSION/atlas/apps/channels/livechat/touchpoint/TOUCHPOINTID

And you can use the following correlation to know the value for region for each domain extension:

• youraccount.mytalkdesk.com ➞ td-us-1
• youraccount.mytalkdesk.eu ➞ td-eu-1
• youraccount.mytalkdesk.ca ➞ td-ca-1

Notes:

• The touchpoint ID can either be identified by flowId or touchpointId. The former flowId was replaced by touchpointId so that it would not be mistaken for the Studio Flow's ID. Both versions are currently supported.
• To customize the widget, add the styles object with the customization keys and its values after enableAttachments: true and before }.

 

Step 2: Create a CSS file

Create a CSS file named chat-iframe.css, containing the following code:

 

Note: Widget customization is not done in the CSS file. This CSS file is meant for the iframe only and not the widget itself.

Step 3: Include the iframe and style in your website

Finally, add a <link> and <iframe> to your website (lines 7 and 11):

The HTML file (chat-iframe.html) and the CSS file (chat-iframe.css) have to be in the same folder as the main page.

For more information, please consult here.

 

Widget Integration via Script

Access  “Admin” > “Channels” > “Chat” > “Touchpoint”. In the Touchpoint tab in view mode, locate the widget code section.

Select the code snippet and click the Copy button. Paste the code snippet before the following closing tag on your own website:

• </body>

Note: Copy it onto every page where you want the chat widget to appear.

 

Chat Widget Customization

In order to better adapt the chat widget to your website’s characteristics, you can customize the widget’s look and the user experience. Please refer to this article for more information.

 

Context Variables

The initial step component on the “Incoming Message” flow in Studio allows you to bring context coming from the chat widget.

It is possible to collect context variables in the following ways:

• Data provided by the visitor: Asking for information in the initial screen through custom fields and custom dropdowns. The visitor will then fill in the requested information.
• Data provided by your system: Receiving information from your website when the visitor opens the chat widget or when the visitor starts a chat conversation.

 

Note: You can use both ways at the same time.

 

Collected variables must be mapped to the “Incoming Message” component of the Studio flow that is assigned to the chat touchpoint. After that, you can use them either to manage which variables you would like to present to your agents as additional context for routing purposes, or build integrations with other Talkdesk Products.

 

Context Variables Received from the Initial Screen

Go to “Admin” > “Channels” > “Chat” > “Touchpoint”, open the “Appearance” tab, and click the Edit button. Enable the initial screen and add the fields that will be collecting the context you need. For more details, please see this section.

Check the Studio arguments related to each field of the initial screen. To know more about Studio arguments, please read the following articles:

• Digital Engagement: Studio Configuration for Administrators
• Studio: Working with Variables

Open the touchpoint’s Studio flow in edit mode. Select the Incoming Message component, add the arguments, and map the respective flow variables:

• “Argument name”: Copy the field’s argument name that is shown on the “Appearance” tab (view mode) and paste it into the argument input box.
• “Map to flow variable”: For the contact details variables, the following naming should be applied:
  • field_name1 > contact_name
  • field_number1 > contact_number
  • field_email1 > contact_email
• For any other argument, any other variable name can be applied.

Finish the configuration according to your requirements and click Save.

 

Context Variables Received from the Website

In the widget code, locate the commented section with the function shown below, and decomment it:

• setContext()

Example: Receiving variables when the conversation is initiated (with static variables).

Next, locate the function shown below and modify its parameters to pass in the desired data:

• webchat.setContextParam()

You will now choose when you want to receive the context variables from your website.

To receive them when the conversation is initiated, keep the function:

• webchat.onConversationStart = function() { setContext() }

And then delete the function:

• webchat.onOpenWebchat = function() { setContext() }

To receive them when the chat widget is open, keep the function:

• webchat.onOpenWebchat = function() { setContext() }

And then delete the function:

• webchat.onConversationStart = function() { setContext() }

The name of the variables you added to the function shown below correspond to the Studio arguments:

• webchat.setContextParam()

Open the touchpoint’s Studio flow in edit mode. Select the Incoming Message component, add the arguments, and map the respective flow variables:

• “Argument name”: Copy the variable name you added to the widget code within the “webchat.setContextParam” function and paste it into the argument input box.
• “Map to flow variable”: For the existing variables, the following naming should be applied:
  • argument that collects name ➞ contact_name
  • argument that collects number ➞ contact_number
  • argument that collects email ➞ contact_email
• For any other argument, any other variable name can be applied.

Finish your Studio flow configuration and Save your configurations.

 

Possible Applications for Context Variables

Show Additional Context to Agents

In the “Manage context” section of the touchpoint’s Studio flow, you can define the context that will be shown to your agents. To do so, open the Studio flow in edit mode, and click on this button: . Then, select the variables you would like your agent to have access to during the chat conversation.

Examples received from the initial screen and an example received from the website.

 

Prefill contact details card

By receiving the visitor’s name, phone number and/or email address, you can populate the contact details card.

For that, you need to expose those variables as context in the “Manage context” section. Open the Studio flow in edit mode, and click: . Then, select the variables corresponding to the contact details.

 

Note: If you get a valid phone number, the agent will have the ability to choose that number when clicking-to-call the visitor.

 

Route Conversations Based on Conditional Statements

With the Conditional Statement component, you can route a chat conversation to a queue that matches the predefined conditions. 

You can use the context variables to set these conditions and later use the “Assign agents to message” component to set the queue to which the chat conversation should be routed to.

 

Other Possible Applications

There are several uses for context variables within different Studio’s components, for instance,  assigning a conversation to a ring group based on the variable’s value in the “Assign agents to message” component.

These variables can also be passed to external systems through integrations or automations that it is possible to configure within Talkdesk’s system.

 

Visitor Identification

In the Conversations app, a visitor will be identified as “Visitor #NNN” if no Contact is created or assigned to the visitor during the chat conversation.

 

Note: If the “Name” field of the “Contact Details” card is populated, the visitor will be identified by that name in the Assigned to you tab, even if the Contact is not saved.

In Reporting, a visitor will be identified by “Visitor #NNN” if no Contact is created or assigned to the visitor when a chat conversation is being handled.

Visitor identification can be done manually or automatically based on how contact information is obtained. The possibilities are:

• Contact is created or identified manually when the data is provided by the visitor: 
  • Option 1: The visitor will provide the requested information, and the agent will populate the “Contact Details” card and then save it as a new contact or merge with an existing contact.
  • Option 2: The visitor will fill in the requested information in the chat widget’s initial screen, and the agent will validate the information that was populated in the “Contact Details” card. It can then be saved as a new contact or merged with an existing one.

In these scenarios, if the same visitor contacts again and the same contact information is provided, Talkdesk will not identify the visitor automatically.

Note: The Contact is not created automatically to allow agents to verify the reliability of the information provided. This step is essential as there is no prevention in place for incorrect or mistaken contact details entered by users in the pre-conversation form, including the possibility of entering someone else's contact information.

 

• Contact is created or identified automatically when the data is provided by your system by receiving the contact information from your website, using the “Chat User Identification” feature.

This feature allows you to send the email address or the phone number of the visitor to Talkdesk, through a designated variable in the chat widget’s code. When the visitor initiates a chat conversation, the system receives the visitor’s phone number or email address, and then it automatically saves it as a new contact or matches it with an existing contact.

In this scenario, if the same visitor contacts again, Talkdesk will identify the contact.

The “Chat User Identification” feature is useful for website sections that demand user authentication. With this feature, visitors can be reliably identified, ensuring that the information being sent originates from the user initiating the chat conversation.

Note: Talkdesk will only create the Contact if the received phone number or email address is in a valid format.

 

Creating and Identifying a Contact Manually

When the contact information is provided by the visitor, agents must decide whether to create (or not) a new contact, or assign (or not) the chat conversation to an existing contact. This is due to the agent needing to validate the provided information.

 

Using a Pre-Conversation Form to Collect the Contact Information

Head to “Admin” > “Channels” > “Chat” > “Touchpoint”. Open the “Appearance” tab and click Edit.

Expand the initial screen section. Now, add custom fields and define them as “Contact name”, “Contact number”, and “Contact email”.

Click “save” and check the Studio arguments.

Open the touchpoint’s Studio flow in “Edit” mode. Select the Incoming Message component and add the arguments, and add the arguments as follows:

• field_name1 > contact_name
• field_number1 > contact_number
• field_email1 > contact_email

Finish the configuration according to your requirements and press Save.

Click the button and select the variables of the contact details:

How It Works

If you are not requesting the contact information in advance, your agents will have to request that information during the chat conversation. 

They must then copy/paste that information into the “Contact Details” card and then save as a new contact or merge it with an existing one.

If you are using the initial screen to request contact information in advance, the “Contact Details”  card will be populated with that information.

Then, agents must validate which information they want to keep and save as a new contact or merge it with an existing one.

 

Creating and Identifying a Contact Automatically

The “Chat User Identification” feature provides an automated process to create and identify visitors that initiate a chat conversation with your agents. 

Visitors can be identified by phone number or email address.

 

Configuration steps

First, locate the following function in the widget code:

• webchat.setContextParam()

To send the visitor’s phone number (in E.164 format) or email address from your website to Talkdesk system, use the variable:

• td_contact_person_identification

 

Note: The data must be received in a valid format.

 

Make sure you keep one or both of the following functions in that section of the widget code:

• webchat.onConversationStart = function() { setContext() }
• webchat.onOpenWebchat = function() { setContext() }

 

How It Works

If the “td_contact_person_identification” variable is populated with a valid phone number or email address, the system will search for a matching phone number and email address in the “Contacts” list.

• If it does not find a match, a new contact is automatically created. The name and the phone number/email address will be populated with the variable’s value.
• If it finds a single match, the contact will be identified.

• If it finds multiple matches, the system will give the option to choose from several matching contacts.

Notes:

• If the variable’s value is empty or is in an invalid format, the system will not create or identify visitors automatically. The manual procedure will be the one to follow. To know more, please check this section.
• If the phone number or email address is provided in the initial screen, the system will override that information regarding contact creation and identification.

 

Additional Resources