Chat Buttons Articles

How to add a chat button to an Outlook email footer

To add a button to your email signature that users click to initiate a chat session, you simply generate the appropriate chat button code and associate it with your Outlook signature.

  1. From the main menu of the operator client, go to Setup > HTML > Generate Chat Button HTML.

    Result: The Generate Chat Button HTML window is displayed.

  2. On the Generate Chat Button HTML window under Type of Chat Button, select Email Signature Chat Button.
  3. In the email signature field, enter the signature that you want your customers to see.
  4. Under Customize Chat Button Images, select the button that users will click to initiate a chat session from your email signature.
  5. Under Email Signature, choose a signature to which the chat button will be appended.
    • Option. Type a new signature directly in the space provided.
    • Option. Click Open to select an existing email signature. The Open file... dialog is displayed with the path: C:\Users\*username*\AppData\Roaming\Microsoft\Signatures. Select a signature and click Open.
  6. On the Generate Chat Button HTML window, click Save.

    Result: The chat button is added to your email signature.

How to set a chat link as a chat entry point

Set a text-based link that a visitor clicks to initiate a chat session.

When implementing chat, your visitors need something to click in order to start a chat session. The term chat entry point refers to the interface element that a visitor clicks to initiate a chat. You set a chat entry point as part of the procedure of generating and inserting an HTML snippet to your site.

  1. From the main menu of the operator client, go to Setup > HTML > Generate Chat Button HTML.

    Result: The Generate Chat Button HTML window is displayed.

  2. On the Generate Chat Button HTML window, at the top of the window under Type of Chat Button, select Web Page Chat Button Text.
  3. Under Customize Chat Window, associate the link with a Chat Window definition.

    A Chat Window definition controls the look and feel and advanced behavior of the interface that is opened when a visitor clicks your link.

  4. Option. Associate your HTML snippet with a Department definition.

    See About the BoldChat 'Department' entity.

  5. Associate your HTML with a Website definition.

    See How to use Website definitions to manage multiple sites.

  6. Option. Pass customer visitor information into the chat session.

    See Custom Visitor Info, Variables: Collecting visitor data.

  7. Copy and paste the code to your site. See Generate and insert HTML to your website.

Optional: Customize Chat Buttons

Note: This article is part of a Quick Start Guide to help you implement your Digital DX environment from scratch.

Every business has its own unique voice and brand identity, and Digital DX gives you the control and flexibility to customize your implementation to your unique business needs.

  1. Click Channels > Chat > Chat Buttons (Floating).
  2. Click on the name of your chat button.
  3. Go to the Settings > Display.
  4. You can select among predefined images in our Button Template library or provide URL links to your own custom button images.
  5. Scroll down to the Positioning section to select where your chat button is displayed on your web page and how it will animate when shown to the visitor.
  6. Save your changes.

Generate chat button HTML

The primary connection between Digital DX and your chat customers is a snippet of HTML code that you generate together with a chat button and insert to your site.

When choosing an HTML snippet for your site, you are asking yourself the following questions:

  • Which button or link are you showing to customers?
  • Are you collecting information about customers so you can analyze and react to visits even before they chat?
  • Are you tracking conversion events so you can relate specific chats to actual sales or other milestones?
  • Are you inviting customers to chat based on characteristics of their visit such as page visited, length of visit, and more.

Here's how to set up a Digital DX chat button HTML snippet to create a "gate" between customers and Digital DX. For this first test we'll create a Floating Chat button.

  1. In the Web Admin Center, choose the type of HTML code to generate:
    Option Description
    Floating Chat Button Select Channels > Chat > Chat Buttons (Floating) when you want to implement a floating chat button and/or monitor customers before chat and/or invite users to chat based on characteristics of their visit.
    Static Chat Button Select Channels > Chat > Chat Buttons (Static) when you want to implement a fixed-position chat button or link on your site.
    Conversion Tracking HTML Select Customers > Conversion Codes when you want to track conversion events so you can relate specific chats to actual sales or other milestones.

    What is the difference between static and floating chat buttons?

    A static chat button is a standard HTML button that is always displayed on your website as a static element. Whether it's a button or just a clickable string of text depends on how you configure your chat button definition.

    Floating buttons are animated by default and they slide into view when the customer moves the mouse over these buttons. When the button slides in, it covers part of your website, essentially creating an extra layer on top of your website content. You can define where the initial shrunk version of the button should appear on your website and how much it should shrunk before a customer moves the mouse over it.

  2. Apply settings to your HTML and associated entities.
    Tip: This article focuses on the "big picture" of how to implement an HTML snippet rather than the potentially long chain of settings that you can make to the various Digital DX entities that can be associated with an HTML snippet, such as Chat Button definitions, Chat Window definitions, Website definitions, Department definitions, Invitation Rulesets, Conversion Codes, and more.
  3. Click Generate HTML and then Copy to Clipboard.

    Result:

  4. Paste the code to your site.
    Important: Modifications to the generated HTML code may cause unexpected behavior and is not supported. For assistance or questions regarding the HTML snippet, contact Support.

    When pasting the HTML code to your site, consider the following in light of your actual site architecture:

    • To activate the code on all pages, paste the code into the footer include of your website before the closing <body> tag.
    • To activate the code per page (on a single page or multiple pages individually), paste the code into any page before the closing <body> tag.
    • If the chat button associated with your HTML uses a layered chat window, make sure your pages start with a <!DOCTYPE html> tag. Without this tag, some versions of Internet Explorer will use quirks mode and open the layered chat window in a pop-up.
    Tip: If you are sending the code snippet to a web developer via email, do not paste the code directly into an email message. Save the HTML code in a text file (Notepad, for example) and attach it to an email.

You must re-copy and re-insert your HTML code after making any of the following changes:

  • When you associate a new chat button (static or floating) with your HTML (rather than modifying an existing chat button)
  • When you associate a new website with your HTML (rather than modifying an existing website)
  • When you toggle Pass custom information about customer on/off
  • When you change the Conversion Code associated with your HTML
  • When you change the invitation rule set associated with your HTML

Show a different chat button image when agents are available/unavailable

To ensure that customers are properly informed about agent availability, you can choose to show a specific chat button image when at least one agent is available and another (or none) when no agents are available.

This feature is part of the chat button setup process for both floating and static buttons.

  1. Create or edit a fixed-position (static) or floating chat button, as follows:
    1. In the Web Admin Center, go to Channels > Chat > Chat Buttons (Static) / Chat Buttons (Floating).
    2. Select an existing chat button or click Create New.
  2. On the Settings tab in the Display section under When Unavailable, choose the expected behavior when no agents are available:
    • Show Unavailable Button: When no agents are available, the Unavailable chat button is displayed to customers as displayed on the Preview pane.
    • Show No Button: When no agents are available, no button is displayed to customers.
    • Show Available Button: When no agents are available, the Available chat button is displayed to customers as displayed on the Preview pane.
  3. You can also select a custom image for your available and unavailable agents that customers can see. To do so, select the Custom image source and enter the available and unavailable chat image URLs into the corresponding fields.
  4. Save your changes.

    Result: The settings are applied to the chat button.

Your chat button is ready to be set as a chat entry point by being associated with an HTML snippet and inserted to a site.

To activate a newly created chat button as a chat entry point on your website, you must paste the HTML code to your site. When editing an existing button, you do not need to paste the code since these settings are not in the HTML code itself, but rather on Digital DX servers.

Customize chat button appearance, position, animation

Change the look and behavior of your chat button.

  1. Create or edit a fixed-position (static) or floating chat button, as follows:
    1. In the Web Admin Center, go to Channels > Chat > Chat Buttons (Static) / Chat Buttons (Floating).
    2. Select an existing chat button or click Create New.
  2. To change your chat button's appearance, go to the Settings tab under Display.
  3. For floating chat buttons you have these additional options:
    • To control where your floating chat button displays on the customer's browser page, go to the Settings tab under Positioning
    • To control how your floating chat button is animated when shown to the customer, go to the Settings tab under Animation
  4. Save your changes.

    Result: The settings are applied to the chat button.

Your chat button is ready to be set as a chat entry point by being associated with an HTML snippet and inserted to a site.

To activate a newly created chat button as a chat entry point on your website, you must paste the HTML code to your site. When editing an existing button, you do not need to paste the code since these settings are not in the HTML code itself, but rather on Digital DX servers.

Set a chat button to be shown in specific countries

You can set chat buttons to be shown to customers in specific countries.

This feature is part of the chat button setup process for both floating and static buttons.

  1. Create or edit a fixed-position (static) or floating chat button, as follows:
    1. In the Web Admin Center, go to Channels > Chat > Chat Buttons (Static) / Chat Buttons (Floating).
    2. Select an existing chat button or click Create New.
  2. At the bottom of the Settings tab, under Locale, clear the checkbox for Show to all countries.
  3. Select countries to include or exclude.
  4. Save your changes.

    Result: The settings are applied to the chat button.

Your chat button is ready to be set as a chat entry point by being associated with an HTML snippet and inserted to a site.

To activate a newly created chat button as a chat entry point on your website, you must paste the HTML code to your site. When editing an existing button, you do not need to paste the code since these settings are not in the HTML code itself, but rather on Digital DX servers.

Associate chats (a chat button) with a department

Associate a chat button with a department to allow chats originating from the button to be tagged with department metadata, which can then be used to assign and organize chats.

This feature is part of the chat button setup process for both floating and static buttons.

  1. Create or edit a fixed-position (static) or floating chat button, as follows:
    1. In the Web Admin Center, go to Channels > Chat > Chat Buttons (Static) / Chat Buttons (Floating).
    2. Select an existing chat button or click Create New.
  2. On the Settings tab, choose the Department to associate with the chat button.
  3. Save your changes.

    Result: The settings are applied to the chat button.

Your chat button is ready to be set as a chat entry point by being associated with an HTML snippet and inserted to a site.

To activate a newly created chat button as a chat entry point on your website, you must paste the HTML code to your site. When editing an existing button, you do not need to paste the code since these settings are not in the HTML code itself, but rather on Digital DX servers.

How to set up a Chat Button definition

The term chat button is used generally to refer to both Custom Chat Button definitions and Custom Floating Chat Button definitions.

Why do we call it a "definition"?

It is important to understand that "chat button" does not refer to a simple button (as in the actual graphical user interface element a visitor clicks), but rather a complex group of settings associated with an actual button, buttons, or string of text. Together these settings make up a definition.

Where do I create chat button definitions?

We recommend creating and managing Custom (static) Chat Button definitions and Floating Chat Button definitions from the following location: Setup > Account Setup > Chats.

What is the difference between static and floating chat buttons?

A static chat button is a standard HTML button that is always displayed on your website as a static element. Whether it's a button or just a clickable string of text depends on how you configure your chat button definition.

Floating buttons are animated by default and they slide into view when the visitor moves the mouse over these buttons. When the button slides in, it covers part of your website, essentially creating an extra layer on top of your website content. You can define where the initial shrunk version of the button should appear on your website and how much it should shrunk before a visitor moves the mouse over it.

How do chat buttons relate to other BoldChat entities?

Chat button definitions can be associated with the following:

  • An HTML snippet
  • A Custom Chat Window definition
  • A Department definition

The direction of the relationship is from HTML snippet to chat button, and from chat button to window or department.

An HTML snippet can only be associated with one chat button definition. A chat button definition can only launch one specific chat window and can only be associated with one department, while a chat window can be launched from multiple buttons or invitations and a department can be associated with multiple buttons.

What is controlled by the chat button definition?

The chat button definition controls the following:

  • The actual button images shown when operators are available or unavailable
  • The position of floating button images on your page
  • Animation settings for floating button images, including resize when not in focus
  • The Chat Window visitors are shown when they click the button
  • The Department associated with the button
  • The countries where the button will be displayed

Which settings impact chat button availability?

The following settings help determine when your chat button is shown to visitors:

  • Operator availability (including operator hours)
  • Website business hours
  • Department business hours
  • ACD settings (queue limits)

How to set a chat button to be shown in specific countries

This feature is part of the Custom Chat Button definition process for both floating and fixed-position buttons.

  1. Using the BoldChat Operator Client, create a custom chat button definition, as follows:
    1. From the main menu of the BoldChat Operator Client, go to Setup > Account Setup. The Account Setup window is displayed.
    2. Choose the type of button to create. On the left menu, click Chats > Custom Chat Buttons > New or Chats > Custom Floating Chat Buttons > New.

    Result: The New Custom Button window is displayed.

  2. Use the direction buttons to move countries between Included Countries and Excluded Countries.
  3. Save your changes.

    Result: The settings are applied to the custom chat button definition.

Your Custom Chat Button definition is ready to set as a chat entry point by being associated with an HTML snippet and inserted to a site.

To activate a newly created button definition as a chat entry point on your website, you must paste the HTML code to your site. When editing an existing button, you do not need to paste the code since these settings are not in the HTML code itself, but rather on the BoldChat server.

How to set up a chat button to leverage a department definition

Associate a chat button with a department to allow chats originating from the button to be tagged with department metadata, which can then be used to assign and organize chats.

This feature is part of the Custom Chat Button definition process for both floating and fixed-position buttons.

  1. Using the BoldChat Operator Client, create a custom chat button definition, as follows:
    1. From the main menu of the BoldChat Operator Client, go to Setup > Account Setup. The Account Setup window is displayed.
    2. Choose the type of button to create. On the left menu, click Chats > Custom Chat Buttons > New or Chats > Custom Floating Chat Buttons > New.

    Result: The New Custom Button window is displayed.

  2. Save your changes.

    Result: The settings are applied to the custom chat button definition.

Your Custom Chat Button definition is ready to set as a chat entry point by being associated with an HTML snippet and inserted to a site.

To activate a newly created button definition as a chat entry point on your website, you must paste the HTML code to your site. When editing an existing button, you do not need to paste the code since these settings are not in the HTML code itself, but rather on the BoldChat server.

How to set a chat button as a chat entry point (fixed-location)

Set a button that a visitor clicks to initiate a chat session.

When implementing chat, your visitors need something to click in order to start a chat session. The term chat entry point refers to the interface element that a visitor clicks to initiate a chat. You set a chat entry point as part of the procedure of generating and inserting an HTML snippet to your site.

  1. From the main menu of the operator client, go to Setup > HTML > Generate Chat Button HTML.

    Result: The Generate Chat Button HTML window is displayed.

  2. On the Generate Chat Button HTML window, at the top of the window under Type of Chat Button, select Web Page Chat Button Image.
  3. Under Customize Chat Button Images, choose a chat button definition to associate with your HTML snippet:
    • To use the default button, do nothing (the default is called My Chat Button)
    • To change the chat button definition, click the three dots ... next to Custom Chat Button. See Setting up Chat Buttons.
    Tip: To see what your chat button or text link will look like on the web page based on current settings, click Open Test Page.
  4. Associate your HTML with a Website definition. See How to set up a Website definition.
  5. Option. Pass customer visitor information into the chat session.

    See Collecting visitor data with Custom Visitor Info and Variables.

  6. Copy and paste the code to your site. See Generate and insert HTML to your website.

How to show a different chat button image when operators are available/unavailable

To ensure that visitors are properly informed about operator availability, you can choose to show a specific chat button image when at least one operator is available and another (or none) when no operators are available.

This feature is part of the Custom Chat Button definition process for both floating and fixed-position buttons.

  1. Using the BoldChat Operator Client, create a custom chat button definition, as follows:
    1. From the main menu of the BoldChat Operator Client, go to Setup > Account Setup. The Account Setup window is displayed.
    2. Choose the type of button to create. On the left menu, click Chats > Custom Chat Buttons > New or Chats > Custom Floating Chat Buttons > New.

    Result: The New Custom Button window is displayed.

  2. On the New Custom... window, under When Unavailable, choose the expected behavior when no operators are available:
    • Choose Show Unavailable Button: When no operators are available, the Unavailable Image URL is displayed to visitors.
    • Show No Button: When no operators are available, no button is displayed to visitors.
    • Show Available Button: When no operators are available, the Available Image URL is displayed to visitors.
  3. Save your changes.

    Result: The settings are applied to the custom chat button definition.

Your Custom Chat Button definition is ready to set as a chat entry point by being associated with an HTML snippet and inserted to a site.

To activate a newly created button definition as a chat entry point on your website, you must paste the HTML code to your site. When editing an existing button, you do not need to paste the code since these settings are not in the HTML code itself, but rather on the BoldChat server.

How to set a floating chat button as a chat entry point (with Visitor Monitoring)

Set a floating button that a visitor clicks to initiate a chat session.

When implementing chat, your visitors need something to click in order to start a chat session. The term chat entry point refers to the interface element that a visitor clicks to initiate a chat. You set a chat entry point as part of the procedure of generating and inserting an HTML snippet to your site.

  1. From the main menu of the operator client, go to Setup > HTML > Generate Floating Button / Visitor Monitor HTML

    Result: The Generate Visitor Monitor HTML window is displayed.

  2. On the Generate Visitor Monitor HTML window, choose a floating button to deploy:
    • To use the default button, do nothing (the default is called My Chat Button)
    • To change the chat button definition, click the three dots ... next to Floating Chat Button. See Configuring chat buttons.
  3. Associate your HTML with a Website definition. See How to set up a Website definition.
  4. Option. Associate your HTML with an Auto-Invite Ruleset definition. See How to invite visitors to chat according to rules.
  5. Copy and paste the code to your site. See Generate and insert HTML to your website.

Collecting visitor data with Custom Visitor Info and Variables

Gather information about visitors and pass it to BoldChat to help operators achieve business goals.

You can pass custom info and custom variables from the HTML code for a Chat Button, Visitor Monitoring, or Conversion Tracking. This article covers the variables that are available per HTML code type.

Chat Button Variables

Select the Pass Custom Visitor Information option when generating Chat Button HTML.

vr: visitor reference
Passes any desired information about a specific visitor. An initial value is not passed to this variable via the operator client.
vn: visitor name
Passes the visitor's name. This variable passes the value of the Name field from the pre-chat form.
vi: visitor information
Passes any desired information about a specific visitor. An initial value is not passed to this variable via the operator client.
ve: visitor email
When using a pre-chat form as part of your Chat Window definition, this variable passes the value of the Email field from the pre-chat form.
vp: visitor phone
When using a pre-chat form as part of your Chat Window definition, this variable passes the value of the Phone field from the pre-chat form.
lc: language code
When using a pre-chat form as part of your Chat Window definition, this variable passes the value of the Language field from the pre-chat form.
iq: initial question
When using a pre-chat form as part of your Chat Window definition or Auto-Invite, this variable passes the initial question from the pre-chat form or pre-chat auto-invite form.
Note: The iq variable must be inserted manually into the WindowParameters section of the Chat Button HTML code in the section highlighted below.

Values are passed when the visitor initiates a chat. Values are shown on the operator grid together with the incoming chat.

Variables within the Chat Button HTML code
Figure 1. Variables within the Chat Button HTML code

Visitor Monitoring Variables

Select the Pass Custom Visitor Information option when generating Visitor Monitoring HTML.

vr: visitor reference
Passes any desired information about a specific visitor. An initial value is not passed to this variable via the operator client.
vn: visitor name
Passes the visitor's name. This variable passes the value of the Name field from the pre-chat form.
vi: visitor information
Passes any desired information about a specific visitor. An initial value is not passed to this variable via the operator client.
ve: visitor email
When using a pre-chat form as part of your Chat Window definition, this variable passes the value of the Email field from the pre-chat form.
vp: visitor phone
When using a pre-chat form as part of your Chat Window definition, this variable passes the value of the Phone field from the pre-chat form.
url: URL
Pass the visitor?s current URL (the URL of the visitor's current page).
curl: custom URL
Pass a URL that differs from the page of origin (that is, do not pass the URL of the visitor's current page). This can be useful for identifying a URL or page that would normally be blocked due to business rules that prevents the page from being displayed because of dynamic or sensitive information.
Tip: When using Visitor Monitoring HTML on a site that requires registration, values can be passed once a visitor signs in to their account. Use the Data Validation feature when passing sensitive data. See How to validate Chats, Visits and Conversions (Data Validation).

All variables are passed from one page to the next and remain set until a new value is passed. This allows for the Visitor Monitoring to maintain the associated value throughout the visit, as well as passing those values to the Conversion Code (see below).


Figure 2. Variables within the Visitor Monitoring HTML code
Variables within the Visitor Monitoring HTML code

Conversion Tracking Variables

Select the Pass Custom Conversion Information and Pass Custom Visitor Information options when generating Conversion Code HTML.

Important: When implementing Conversion Tracking, you must ensure that your Visitor Monitoring HTML, Conversion Tracking HTML, and Chat Button HTML are all associated with the same Website definition.
ca: conversion amount
Passes the conversion amount. Requires a number (with a decimal point for decimal values).
cr: conversion reference
Passes the conversion reference (such as an invoice or order number). This is a uniquely valued parameter. Duplicate conversion references are not allowed and will not trigger new conversions unless you change either the conversion reference or use a different conversion code (or leave it blank).
ci: conversion information
Passes any desired information about a specific visitor. An initial value is not passed to this variable via the operator client.
vr: visitor reference
Passes any desired information about a specific visitor. An initial value is not passed to this variable via the operator client.
vn: visitor name
Passes the visitor's name. This variable passes the value of the Name field from the pre-chat form.
vi: visitor information
Passes any desired information about a specific visitor. An initial value is not passed to this variable via the operator client.
ve: visitor email
When using a pre-chat form as part of your Chat Window definition, this variable passes the value of the Email field from the pre-chat form.
vp: visitor phone
When using a pre-chat form as part of your Chat Window definition, this variable passes the value of the Phone field from the pre-chat form.

How to Set up Custom Variables

This section helps you implement custom variables and put them to use to solve business needs.

Variable values remain the same from page to page unless changed. With this in mind, we do not recommend using both Chat Button custom variables and Visitor Monitoring custom variables on the same page. A good example of why this is not necessary would be when a customer comes to your site and signs into their account. The Visitor Monitoring code sets the custom variables appropriate to the information from the customer's account. The customer then decides to launch a chat, these variable are then passed into the Pre-Chat form and pre-populate the form for the customer. By having the variables also available in the Chat button code, it opens the possibility of having the values from the Visitor Monitoring code overwritten by the Chat Button variable assignment.

Passing Conversion Tracking Variables

Once the code containing your custom variable has been generated, you must edit the script to set the variable assignment. This is easily accomplished with a little JavaScript or with your preferred scripting language via the getPageViewer directive.

Note: Conversion Tracking Variable values are automatically updated each time the VMS code is run.

In the above highlighted example, customerId is a variable that you would create and associate the desired value from the page. Please notice that both vi variables have been set, this is necessary to ensure the variable assignment functions for both JavaScript enable and Non JavaScript enable browsers.

Now, let's take look at how you would set the value for customerId using a little JavaScript. Once the value is set it will then be passed to the vi variable, this occurs because we have set vi=customerId or more specifically, the value of customerId will be assigned to vi.

Assuming the value of the customer number is exposed in some way, such as an element identifier on the web page. For example, we used a div tag with an Id set to CustomerNumber; this identifies it and enables us to extract the inner value and then assign it to our variable. See below for a full code example.

The code above extracts the value from the div element (123456789) and then assigns it to customerId which in turn is then assigned to vi. Once this is assigned, it is available to be viewed in the visit grid within BoldChat.

Passing Custom Variables on Pre-Chat Forms

You can pass custom information to BoldChat using custom variables via Chat Button or VMS code with the WindowParameters directive. The number of custom variables is not limited.

Note: Custom variable values cannot be updated once the chat is started, as opposed to the Conversion Tracking variables mentioned above.
  1. Click New to add a custom parameter to your Chat Window definition under Setup > Account Setup > Chats > Custom Chat Window > Pre-Chat Form > Custom Fields.
  2. Set the field Type to Hidden.
  3. Add the parameter to the VMS or Chat Button code on your page via WindowParameters.
    Important: The variable name must start with customField_.

    Let's say that you need to pass the following additional variables:

    • CampaignID
    • VisitorFromID
    • CreativeID

    In this case, construct the WindowParameters directive as follows, where value1, value2 and value3 are the respective values:

    var WindowParameters="customField_CampaignID=value1&customField_VisitorFromID=value2&customField_CreativeID=value3";
    _bcvma.push(["setParameter", "WindowParameters", WindowParameters]);
Note: Special and unsafe characters must be escaped. With JavaScript, use the encodeURIComponent() method to convert such characters instead of escape(), as it has been deprecated.

Result: The custom variable and the new values now appear in the Chat Details window.

How to generate an HTML Snippet

The primary connection between BoldChat and your site is always a snippet of HTML code that you generate in BoldChat and insert to your site.

Members of a Permission Group with the following account permissions can use this feature:
  • Can Generate Chat Button HTML
  • Can Generate Visitor Monitor HTML
  • Can Generate Conversion Tracking HTML

The HTML snippet tells BoldChat servers how you are using BoldChat. When choosing an HTML snippet for your site, you are asking yourself the following questions:

  • Which button or link are you showing to visitors?
  • Are you collecting information about visitors so you can analyze and react to visits even before they chat?
  • Are you tracking conversion events so you can relate specific chats to actual sales or other milestones?
  • Are you inviting visitors to chat based on characteristics of their visit such as page visited, length of visit, and more.

Regardless of your reason for using BoldChat and the details of your exact implementation, you must integrate a BoldChat HTML snippet to create a "gate" between visitors and BoldChat servers.

  1. From the main menu of the operator client, go to Setup > HTML and select the type of HTML to generate:
    • Generate Floating Button / Visitor Monitoring HTML. Select this option when you want to implement a floating chat button and/or monitor visitors before chat and/or invite users to chat based on characteristics of their visit
    • Generate Chat Button HTML. Select this option when you want to implement a fixed-position chat button or link on your site.
    • Generate Conversion Tracking HTML. Select this option when you want to track conversion events so you can relate specific chats to actual sales or other milestones.
  2. Apply settings to your HTML and associated entities.
    Tip: This article focuses on the "big picture" of how to implement an HTML snippet rather than the potentially long chain of settings that you can make to the various BoldChat entities that can be associated with an HTML snippet, such as Custom Chat Button definitions, Custom Chat Window definitions, Website definitions, Department definitions, Auto-Invite Ruleset definitions, Conversion Code definitions, and more.
  3. Click Copy to Clipboard.
  4. When pasting the HTML code to your site, consider the following in light of your actual site architecture:
  5. Paste the code to your site.
    Important: Modifications to the generated HTML code may cause unexpected behavior and is not supported. For assistance or questions regarding the HTML snippet, contact Support.

    When pasting the HTML code to your site, consider the following in light of your actual site architecture:

    • To activate the code on all pages, paste the code into the footer include of your website before the closing <body> tag.
    • To activate the code per page (on a single page or multiple pages individually), paste the code into any page before the closing <body> tag.
    • If the chat button associated with your HTML uses a layered chat window, make sure your pages start with a <!DOCTYPE html> tag. Without this tag, some versions of Internet Explorer will use quirks mode and open the layered chat window in a pop-up.
    Tip: If you are sending the code snippet to a web developer via email, do not paste the code directly into an email message. Save the HTML code in a text file (use Notepad, for example) and attach it to an email.

You must re-copy and re-insert your HTML code after making any of the following changes:

  • When you associate a new Custom Chat Button or Floating Chat Button with your HTML (not modify an existing)
  • When you associate a new website with your HTML (not modify an existing)
  • When you toggle Pass Custom Visitor Information on/off
  • When you change the Conversion Code associated with your HTML
  • When you change the Auto-Invite Ruleset associated with your Visitor Monitoring HTML

If you no longer want to display a chat window on a specific web page, remove the chat button code from the HTML source of that page.

How to validate Chats, Visits and Conversions (Data Validation)

Enterprise subscribers can set Digital DX to validate all chats, visits, and conversions. Use this feature to ensure that incoming chats originate from the Website associated with the chat button and that chat and visit parameters provided by the visitor cannot be viewed or modified by any third party. When visitor monitoring and/or conversion tracking is enabled, this feature also ensures that the visit/conversion data originates from the website with the monitoring/conversion HTML code.

Setup

Data validation is set for a Website definition.

Fastpath: From the main menu of the Digital DX Desktop Client, go to Setup > Account Setup > General > Websites > New/Edit > Data validation tab > Enable data validation

When enabled and required, all chat, visit, or conversion data must be validated as originating from your server before reaching an operator.

By selecting the All HTML must be associated with a Website definition option in General Account > Settings > Extra Security, and ensuring that all Website definitions require validation, every chat assigned to an agent of the account is guaranteed to be validated.

Note: An Enterprise subscription is required.

Data Validation Methods:

  • PGP: The data passed to Digital DX can be PGP encrypted using our public key and signed with your private key to completely hide the parameters passed into chat
  • SHA-512: The visitor can be disallowed from tampering with the data passed to Digital DX by generating a hash of the data using a private hashing key

Both methods rely on a new parameter in the HTML: SecureParameters. This replaces custom variable parameters such as VisitRef and VisitInfo. Any visit, chat or conversion related data when validation is enabled that are not passed into the SecureParameters variable will be ignored by the server. Additionally, if security fails, the chat, visit or conversion will fail as well.

Important: You must define the SecureParameters variable for both the chat and visit types to have proper encryption.

For browsers with JavaScript disabled, Digital DX loads an image inside the noscript tag to register the visit/conversion. In this case, use the parameter secured to pass the secured parameters.

PGP Encryption

Passed parameters should be URL-form encoded into a single string (for example, VisitName=Robert%20Smith&VisitEmail=r.smith%40gmail.com). This is what you will PGP encrypt, sign and pass as the SecureParameters variable. The final string passed in as the SecureParameters variable will look like this:

"-----BEGIN PGP MESSAGE-----\nVersion: BCPG v1.50\n\nhQEMA9/66abKVXSZAQf/UT+3OtVApwD0H+Fv2S5bXqMfkvHEQgbvXLwMiLPRy2gs\nv3L4EbMGMoIjt8Leg1D/M8bgbovYEs546LwXdAcOQt/n4c2+9WB8mph9lDW4+z9U\n5eWwwDjatrF8yKvpVM+g0+y8SEtuuBr2xrNfXBaCXRSyEN/88tl7drvIjzAg5lUV\nuPMtDvLnE9bAhu02FQx04Dc0lKGDROPlXCp/6tW6rXRmdvZfPRe4GDCzkHoZVOGR\nByNMD1swSIWC60IL5so4wWvmOqgP/fU57W2QNz7wmF9RtSG+L8zdhYX0BKdQAOVL\nKzhRtoMbBpNcT1m0prFhw40sfGDcVnPLJhD4RvLv79LBpwE2HeW3LNm6ZH45ou1A\nmIzik8ZGExDVLY4N9tax6goP1tYXTOq2Zc/XuwIQHhXMdEZaxeLppsjt1cOym/BV\n/2y8uPO8DPQa4jTXDPOsmLJpzAJMnk3EhMMaDDzOIS32i8IyY2sYPgd651ifXrO7\n38zCnPC6zMByBuwqvoT5xlELYE0KFRvm7fmYhYK2KHQrazneESRX0TnLrI3k6mSR\ndK/MSLVb5v6aNY6f/RySADE/XqhEJ8DVXRyN8Qum+vtl1PMGOothaFemT4bZbZ+8\nw7PKCZSFWqKcEZyk1eJl02V8u1VgmYkaya2vvLGFqTGxSVk6jALrPcIyCxW7z1XV\nVSwdraDtqMyJ6aAOkUEF5qidyupoajpyjxWRsaM5Al/VJOjR6u97fu9aSNtGNW73\nmmpqBh2MwbPvO5wWTadN3VLRowlkzNWIX0pdKvdA69fQ4NlGLra9bmH0ofjQuCl9\nNTRAqn5pbyb8aCyWtxMTtgxZwgNsdWMg0yYMLV+HdH3zVT6Bc+lExzOl5rxOXxbz\nQxj3Bqil615AQP2JIi4A6FQ0+Om1xNtm+t6eIFAR3GDYjaw+GgBv+r4mdXRfz/6I\nOQysntG1rMgCHjXg6B2y46PAp2tdVptJVcUhyz93m99MBT3nKtUmmb5sVHJRnmIg\nQjQv+3SKjVnMwncHveNXosBBeem2Vdrb+lVbI3eQ0XD/fEi43oQdl8hSNuqfw1jy\nDz4Gi2EaYyaDqrRMS6nEMaOujfD6zcPpbR8MSbmQTvmi5eOWPQZhopXrN2ogxtea\n5jUabllMN5PxGkXWBAhWG1hUVkYH8SMucQ==\n=/htM\n-----END PGP MESSAGE-----"

You can provide your public signing key on the New/Edit Website window. Digital DX uses it to generate a new server key in the back-end for encrypting the data and providing you a public key for encrypting the data. The server-side generated keys are 2048-bit, and we recommend you use the same key size for your signing key.

Data validation relies on asymmetrical cryptography: parameters are encrypted using your private key and the public key of the server. Digital DX decrypts parameters using its private server key and your public key.

For your first test, you can encrypt your data and pass it into the website setup data verification area. The server will decrypt it, verify the signature, and return the plain-text data or any error messages encountered.

SHA-512 Hashing

The most secure method of validating chats is the full PGP encryption. However, for ease of implementation, we also support the SHA-512 hashing algorithm.

The parameters you want to pass should be URL-form encoded into a single string (for example, VisitName=Robert%20Smith&VisitEmail=r.smith%40gmail.com). The private hashing key will be concatenated in front of this value, and then hashed using the SHA-512 algorithm. The hashed value should then be hex-encoded and appended to the front of the SecureParameters variable. The final string passed in as the SecureParameters variable will look like this:

"1939D964B68EBFA61DE8C0B45D0C3C4836169C87DAB362116474A3B67B113B65F0172D3FA3191EC3525DA3E50B11A09B00B0A2869A1585EF148420347DE17A9EVisitName=Robert%20Smith&VisitEmail=r.smith%40gmail.com"

On the New/Edit Website window, you can create and delete the private hashing keys used to validate the visitor data.

For your first test, you can hash the key and data to append the data to the hash and pass it to the data verification area of the New/Edit Website window . The server will parse out and verify the hash, returning plain-text data or any error messages.

Parameters

Once validation is enabled, you can use both original parameter names ("vr", "vn", etc.) and human-readable versions:

Friendly Name Original Meaning
URL url The current page of the visitor (also the chat launch url when a chat is launched)
ReferrerURL referrer The referring page of the visitor
VisitName vn The name of the visitor
VisitRef vr A reference value for the visitor
VisitInfo vi An information value for the visitor
VisitEmail ve The email address of the visitor
VisitPhone vp The phone number of the visitor
CustomURL curl The custom URL for the chat
VisitorIcon vicon The chat icon for the visitor
OperatorIcon oicon The default chat icon for the operator
LastName ln The last name of the visitor
FirstName vn The first name of the visitor (synonymous with VisitName)
InitialQuestion iq The initial question for the visitor in chat
ConversionRef cr The conversion reference value for the conversion (must be unique per conversion code)
ConversionInfo ci An information value for the conversion
ConversionAmount ca The amount of the conversion (should be a number simply as 1000.15 for one thousand and fifteen one hundredths)
LanguageCode lc The language code for the chat
customField_[name]   Value of the custom field with the given name

Additional fields that require validation:

Friendly Name Original Meaning
ChatButtonID cbdid The ID of the chat button used to launch the request (which will additionally set the department and chat window if not overridden with another parameter)
FloatingChatButtonID cbdid The ID of the floating chat button used to launch the request (synonymous with ChatButtonDefID)
ChatWindowID cwdid The ID of the chat window to show to the visitor in chat
DepartmentID rdid The ID of the department to which the chat should be assigned
OperatorID roid The ID of the operator to whom the chat should be assigned
ConversionCodeID ccid The ID of the conversion code
InvitationID idid The ID of the associated Auto-Invite Ruleset

Finally, there are several validation-related fields for enhancing chat functionality once the chat is validated:

Friendly Name Original Meaning
Type type The type of the request to enforce. Chat, visit, or conversion. Recommended on all requests.
Expiration expires The time when the request should no longer be considered valid. Recommended on all requests. Counted in milliseconds from midnight 1970-01-01 UTC.
Note: The expiration should allow for a realistic duration of a session, and not too short.
ChatKey ck A unique identifier for this chat request. Repeated chat launches with this key will fail. Recommended on all chat-type requests.
Note: Assign this parameter to a session ID or similar to allow for launching more than a single validated chat during a session.
VisitorKey vk A unique identifier for this visitor. If an operator blocks the chat, it blocks any chat/visitor with this VisitorKey from re-launching chat.
Unsecured unsecured An & separated list of parameter names. These parameters when not present in the validated data can be pulled from the query string of the request normally and/or changed/populated without server validation. For example: VisitName&InitialQuestion&VisitPhone (note the & must be URI encoded to %26 when it is part of the secure parameter string.)

API Parameters

If you are using the chat API, the following parameters are required when the chat is created:

Friendly Name Original Meaning
APIKey APIKey The API key being used. This must match the API key passed in through the authentication header.
Data Data Pre-populated data passed into the chat. (Note: Individual fields must be listed in the 'Unsecured' parameter to not require validation.)

Troubleshooting and Error Messages

Do not modify the HTML code generated by Digital DX as it may result in receiving errors. When you click Generate HTML on the Channels > Chat Buttons > HTML page, copy the complete generated code as is into the HTML source of the website that visitors see. Improper setup can result in the following errors:

Chat Not Validated
You have not passed in the required validation. Either there is no validation, that is the encrypted message is blank, or the Type parameter is missing or incorrect. The Type parameter may be incorrect, for example, if it is set to visit before adding a floating chat button.
Error Validating Chat
You tried to validate the chat, but the hash/encryption process was unable to either decrypt or verify the information.
Validated chat launch has expired
You are passing in an Expiration timestamp that is in the past. Make sure of the following: Confirm that your server's clock is accurate; Confirm that you are passing in the time dynamically at chat launch; Confirm that you are providing a sufficient buffer so chats can't be launched after they expire.
Validated chat launch has already been used
You are passing in a ChatKey value that has already been used to launch a chat. Confirm that the chat key is unique per potential chat launch or is being dynamically generated at chat launch.

If visitor monitoring or conversion tracking is not being generated correctly, use the verification area of the New/Edit Website window to verify that the data has not expired and that type is set correctly.

HTML Code Structure

Sample generated HTML is given below. When HTML is generated with an associated Website definition that has Data validation enabled, the generated HTML includes the comment /* Requires Authentication */. This provides sample data that has not been validated. You can add or remove what is needed from the data on your server, then validate the data and replace the value (either with the hash appended in the case of SHA-512, or just the raw encrypted PGP data).

For chat launches, it is best to use the function callback method to make an asynchronous call to your server to validate the chat and return the validated data.

How to monitor visitors without displaying a chat button

Set your site to monitor visitor activity without displaying a chat button upon entry. Use this solution when you want to be able to invite visitors to chat manually or according to certain criteria.

With this solution the primary connection between BoldChat and your site is a snippet of code called Visitor Monitor HTML.

  1. Set the default Floating Chat Button to None.

    This ensures that no button is displayed to visitors upon entering a site with Visitor Monitoring HTML.

    1. From the main menu of the operator client, go to Setup > General Account Settings.
    2. On the General Account Settings window, under Default Floating Chat , click the X to set the value to None and save your changes.
  2. Generate Visitor Monitoring HTML, as follows:
    1. From the main menu of the operator client, go to Setup > HTML > Generate Floating Button / Visitor Monitor HTML
    2. On the Generate Visitor Monitor HTML window, under Floating Chat Button, click the X to set the value to None.
    3. Associate your HTML with a Website definition. See How to set up a Website definition.
    4. Option. Associate your HTML with an Auto-Invite Ruleset definition. See How to invite visitors to chat according to rules.
  3. Copy and paste the code to your site. See Generate and insert HTML to your website.

Monitor visitors on a website

BoldChat?s Visitor Monitoring tracks visitors on your website in real time and provides detailed information.

  1. IP and Reverse IP: See the IP address and Reverse IP (host name) of each visitor.
  2. Entry URL Tracking: View the Entry URL of every visitor (useful to see which visitors came from ad campaign #1 vs. ad campaign #2).
  3. Proactive Invitations: Automatically invite visitors to chats based on customizable rules.
  4. Geo-Location: Enables showing the country, region, and city for any visitor on your website.
Important: In order to take advantage of these visitor monitoring features, Visitor Monitoring must be implemented throughout your site. Learn more in the Setup and Customization Guide.

Create a Floating Chat Button

Chat buttons are entry points that visitors use to engage with you. They can be customized to meet the needs of each area of your site.

Now you?ll create your first chat button and generate a very important snippet of HTML code. You?ll use the HTML code on your site to deploy chat; don?t worry if you aren?t ready for that step yet ? you can also preview test chats from within the Bold360 Admin Center.

Note: This article is part of a Quick Start Guide to help you implement your Bold360 environment from scratch.

To see the below steps in action, view our tutorial:

  1. In the Web Admin Center, go to Channels > Chat > Chat Buttons (Floating).
  2. Click My Chat Button to edit.
  3. From the Chat Window drop-down, select My Chat Window that you have previously set up.

  4. If you have one department, select it under Department. This will route any chats that come in through this button to agents within that department.
    Note: If you have multiple departments, you can find more information on your routing options in Route chats to your agents.
  5. We recommend using your own custom image for the button itself. To do so, select Custom for Image Source. This custom image should be hosted on a URL, so that you can point to the button in Available Chat URL.
  6. We also recommend using another custom image for an unavailable button. To move forward with this recommended approach, select Show Unavailable button under When Unavailable. This custom image should also be hosted on a URL, so that you can point to the Unavailable button within Unavailable Chat URL.
  7. Once you have completed all the steps outlined, you are ready to generate the HTML to place on your website. To do so, on the left side of the page, go to the HTML tab.
    1. Under Website, select My Website.
    2. Under Auto-Invite Ruleset, select My Invite Ruleset .
    3. Click Generate HTML.

      You may be prompted to save your changes.

    4. Once HTML is generated, click Copy to clipboard.
    5. Paste this code into your favorite text editor such as Notepad. We do not recommend pasting code into Microsoft Word as it can break the code with styling or line breaks. Our best practice recommendation is to deploy this code to a staging site first. From there, review the widget and make any changes you want. Upon doing so, regenerate the code and then send it to your web developer to be added to all pages on your live website! Note that any test data will appear in reporting.
      Note: If you don?t have a custom button image, you can use our default image by keeping Image Source set to Predefined options.

Need more info? There?s a section about chat buttons in our Support Center.

Chat button setup

Configure the settings associated with the button or text that customers click to initiate chat.

Note: To understand the relationship between a website, a chat window, and a chat button, consider the following:
In Bold360, a website is a group of settings that helps you manage your Bold360 strategy across multiple sites or domains. Websites help you track the origin of visits and manage business hours. When used with the Chat Rule Engine, they help you manage incoming chat items.
The website also contains the code of a "chat button", which does not only refer to a simple button on the user interface that a customer clicks, but also a complex group of settings associated with that button. These settings include button images, position, animation, associated departments, the countries where the button is displayed and so on.
When the customer clicks the chat button, a chat window opens, which again is not only a simple window on the user interface, but also a complex group of settings that control the layout and content of that window.
To interact with customers, first you have to set up a website and then a chat window. Subsequently, create a chat button and associate that button with the chat window and the website.

It is important to understand that "chat button" does not refer to a simple button (as in the actual interface a customer clicks), but rather a complex group of settings associated with an actual button, buttons, or string of text:

  • The actual button images shown when agents are available or unavailable
  • The position of floating button images on your page
  • Animation settings for floating button images, including resize when not in focus
  • The chat window customers are shown when they click the button
  • The department associated with the button
  • The countries where the button will be displayed

The following additional settings help determine when your chat button is shown to customers:

  • Agent availability (including agent hours)
  • Website business hours
  • Department business hours
  • Automatic Distribution settings (queue limits)

What are best practices for setting up chat buttons?

  • In addition to a floating button, you should also have static chat buttons prominent in header and footer.
  • ?????Ensure all parameters are defined when generating the button HTML code (website, department when necessary, window as well as the Pass custom information about customer option enabled).
  • Easy for customers to find answers or help
  • Easy access makes for a positive customer experience
  • Allows for customizing the initial button that customers will interact with.
  • Ensuring that parameters are set up from the beginning will ensure easier, more flexible, and more sustainable management in the future. If any of these parameters need to be added or changed down the line, it will require re-deployment of the code, adding risks and delays.

Announcements

Genesys DX/Bold360 End of Life: January 2024

The Genesys DX (Bold360) platform will end of life on January 31st, 2024. This difficult decision was announced in March, 2023.  

Genesys continues to make a strong commitment to Genesys Cloud, while tightening the portfolio to further accelerate feature growth on the platform. Part of that included bringing over key Genesys DX features to Genesys Cloud CX, such as Knowledge Optimizer that focuses on ease-of-use knowledge management. Digital only licenses for Genesys Cloud were also introduced late last year, which are suitable to those who are not looking for voice capabilities or who need agent seats that only feature support for digital channels. 

Details on the end of life timeline

As of January 31st, 2024, access to Genesys DX product interfaces and customer-deployed components stop to function. Users will no longer be able to log into product interfaces, and all of the boldchat/bold360/nanorep domains will become unavailable for use. If you are curious on what the code on your website related to this might look like and how to remove it, we encourage referencing this post on the DX community

After January 31st, 2024, admins will still be able to get access for an additional 30 days. This period is meant to allow for extracting the necessary data from the platform. Historical data extraction from your account will be available to retrieve by data extraction APIs (Bold360 APIs and Nanorep APIs).