HOW-TO: LiveConnect Web Chat Widget

What’s on this page?

• Overview
• Install LiveConnect Web Chat widget on your website
  • Prerequisites: Package Manager
  • Recommended option: Install using Google Tag Manager
  • Alternate option: Embed LiveChat directly into HTML
  • Initiate the chat widget
• Configure LiveConnect Web Chat widget
  • Sample configuration code
  • Configuration options
    • Capture user data before chat start
    • Handle situations when store associates are unavailable
    • Modify user identity storage behavior of browsers
    • Activate embedded mode
    • Use custom CSS
  • API reference
  • Customizing UI text
    • Localization
    • Supported languages
  • Change supported languages
    • Sample code: customizing strings
    • Customize the Contact Us button

Overview#

Tulip LiveConnect Web Chat Widget connects customers visiting your e-commerce sites with retail store associates who are using the Tulip LiveConnect app on their iPhone or iPad.

Retailers can install the Web Chat widget on their e-commerce site to enable customers to chat with a local store associate while shopping on the site. The chat widget can be configured and customized to fit the retailer’s brand style guidelines.

Description of functionality

When a customer opens the chat widget for the first time, they’re prompted to provide their name and other configurable contact details. After providing their details, the customer will automatically be entered into the chat routing workflow to get connected to an associate at a nearby store.

Once a customer is successfully routed to a store’s Chat Requests queue, any associate from the store will be able to Accept the message and begin chatting with the customer. Customers can send text and upload photos through the web chat widget to communicate with the store associate.

All messages from web chat are indicated as such in the conversation window and in the conversations list, so associates will be able to clearly differentiate conversations on web chat from other channels.

Install LiveConnect Web Chat widget on your website#

You can install this widget either via npm, using Google Tag Manager, or linked in HTML.

Prerequisites: Package Manager#

Include the package in your project using npm:

npm i @tulipnpm/livechat@latest

Recommended option: Install using Google Tag Manager#

Many e-commerce websites use Google Tag Manager to inject third-party JavaScript into their pages. This is the recommended distribution method of LiveConnect Web Chat.

To install LiveConnect using Google Tag Manager, complete the following steps:

1. Open Google Tag Manager and select your e-commerce site’s account.
2. Create a new Tag of type Custom HTML.
3. Paste the following code in the tag. Replace <INTEGRATION_ID> with your integration ID. Additional configurations can be made in the lwc_config object.

<script src="https://cdn.jsdelivr.net/npm/@tulipnpm/livechat@latest/dist/tuliplivechat.min.js"></script>
<script>
    tuliplivechat.init({ integrationId: '<INTEGRATION_ID>' });
</script>

4. Create a Trigger for DOM Ready and link it to your Tag.
5. Name and save the Tag.
6. Preview and publish your changes.

Alternate option: Embed LiveChat directly into HTML#

<script src="https://cdn.jsdelivr.net/npm/@tulipnpm/livechat@latest/dist/tuliplivechat.min.js"></script>

Initiate the chat widget#

Use the following configuration to initiate the chat widget:

tuliplivechat.init({ integrationId: '<INTEGRATION_ID>' });

Configure LiveConnect Web Chat widget#

Configuration options are provided when initializing the widget with init({..})

The integrationId is also a configuration option. It identifies your widget to Tulip. Tulip provides you with this value when you purchase Tulip LiveConnect Web Chat.

Sample configuration code#

var lwc = tuliplivechat;
var config = {
    integrationId: '<INTEGRATION_ID>',
    displayStyle: 'button',
    imageUploadEnabled: true,
    fixedIntroPane: false,
    buttonIconUrl: 'https://retailer.com/logo.png',
    buttonWidth: '58px',
    buttonHeight: '58px',
    businessName: 'Retailer',
    businessIconUrl: 'https://retailer.com/logo.png',
    customColors: {
        brandColor: 'ee3d50',
        conversationColor: '151043',
        actionColor: '333333',
        contactUsButtonColor: '452BD6'
    },
    contactUsButtonUrl: 'https://retailer.com/contact',
};
lwc.init(config);

Configuration options#

Child options of customColors

Capture user data before chat start#

Prechat Capture allows you to capture a user’s data, like name and email, before the start of a conversation.

When configured, the chat input is initially disabled and the user is greeted by a welcome message and a form asking for their name.

Once the form is successfully submitted, a thank you message is sent to the user and the conversation is then initialized, connecting the user to your business.

Child options of prechatCapture

Attributes of prechatCapture.fields

Sample code: prechatCapture configuration

config.prechatCapture: {
    enabled: true,
    enableEmailLinking: true,
    fields: [
    {
        type: 'email',
        name: 'email',
        label: 'prechatCaptureEmailLabel',
        placeholder: 'prechatCaptureEmailPlaceholder',
    },
    {
        type: 'text',
        name: 'name',
        label: 'prechatCaptureNameLabel',
        placeholder: 'prechatCaptureNamePlaceholder',
    },
    {
        type: 'select',
        name: 'country',
        label: 'prechatCaptureCountryLabel',
        placeholder: 'prechatCaptureCountryPlaceholder',
        options: [
            {
                name: 'us',
                label: 'United States',
            },
            {
                name: 'ca',
                label: 'Canada',
            },
        ],
    }
    ]
}

Overriding default text

In order to override the text that you set in a prechatCapture configuration, you must have a customText configuration as well. For more details, see

Customizing UI Text. The value of the label or placeholder must match the key of whatever is in the customText configuration for it to change.

For example: if you wanted to change the name object in the fields list of a prechatCapture config and you wanted to customize the label’s text in two different languages, you would have an additional config that would look like:

config.customText: {
    'en-US': {
        prechatCaptureNameLabel: 'this is an overridden name label',
    }
    'fr': {
        prechatCaptureNameLabel: 'ceci est une étiquette de nom remplacée',
    }
}

Note: The key prechatCaptureLabel is the same as the value in the config.preCapture object for the name label. If they don’t match, it displays the text of whatever the value is in the prechatCapture object. If they match, then the text is customized based on what language the user is in.

Default prechatCapture configuration code

{
    enabled: true,
    fields: {
        type: 'text',
        name: 'name',
        label: 'prechatCaptureNameLabel',
        placeholder: 'prechatCaptureNamePlaceholder'
    }
}

Handle situations when store associates are unavailable#

When enabled, away mode will display a message to the user informing them that there are no associates able to chat currently after a certain period of time without a response. Away mode takes in two object arguments: pooledConversations and assignedConversations. The split in configurations is to allow for different behaviour between conversations that are assigned to an associate and ones that have not been accepted by anyone.

The customer can also be prompted to transfer the conversation to a third party integration. This enables the conversation to continue off of the web chat. If a conversation is switched to a third party channel, the away messages are not sent.

Sample code: Away Mode configuration

awayMode: {
    pooledConversations: {
        enabled: true,
        unresponsiveTime: 60,
        showChannelSwitchPrompt: true
    },
    assignedConversations: {
        enabled: true,
        unresponsiveTime: 600,
        showChannelSwitchPrompt: false
    }
}

Modify user identity storage behavior of browsers#

By default, LiveConnect Web Chat will store the identity of users in the localStorage of the browser. Using localStorage will persist the user identity throughout browser sessions, including page reloads and browser restarts.

To clear the user identity once the browser is closed, use sessionStorage instead. To learn more about Web Storage, see Web Storage API reference on Mozilla.org.

Activate embedded mode#

As described above, to activate the embedded mode, call the embed method after running your init function. This method accepts the DOM ID of the element which will be used as the container where the widget will be rendered. The embedded widget will take the full width and height of the container.

tuliplivechat.init({
    integrationId: '<integration-id>'
});

tuliplivechat.embed('chat-container');

Use custom CSS#

To apply your own custom CSS to our default elements, we allow for passing in a URL to a hosted CSS file using the cssOverwritePath configuration. This CSS file will be added to the styles used on the widget as well as the chat window. Changes to the styling can be made by using the classes and IDs on the HTML elements that already exist and modifying the properties.

For example, if you wanted to make the chat window have no border radius you could apply the following to your hosted CSS file.

#container #wrapper {
	border-radius: 0px !important;
}

API reference#

You can interact with the chat widget using the following exposed methods:

• openChatWindow
• closeChatWindow
• removeChatWidget
• hideChatBubble
• showChatBubble
• isConversationActive
• setChatWindowStyle

openChatWindow

Opens the conversation widget. This method takes an optional boolean parameter. If the parameter is true, we will open the chat window and if it is false, we will close the chat window.

tuliplivechat.openChatWindow();
tuliplivechat.openChatWindow(true);
tuliplivechat.openChatWindow(false);

closeChatWindow

Closes the conversation widget.

tuliplivechat.closeChatWindow();

removeChatWidget Removes the chat widget from the DOM. Will need to be re-initialized if needed again.

tuliplivechat.removeChatWidget();

hideChatBubble Hides the chat widget from the DOM by changing the display on #web-messenger-container.

tuliplivechat.hideChatBubble();

showChatBubble Shows the chat widget to the DOM by changing the display on #web-messenger-container to block. Does not make the chat widget appear after running removeChatWidget. This method takes an optional boolean parameter. If the parameter is true, we will show the chat bubble and if it is false, we will hide the chat bubble.

tuliplivechat.showChatBubble();
tuliplivechat.showChatBubble(true);
tuliplivechat.showChatBubble(false);

isConversationActive Returns a boolean whether the current conversation is active or not.

tuliplivechat.isConversationActive();

setChatWindowStyle Takes in an object of CSS key to value pairs and applies the styles to the chat window.

tuliplivechat.setChatWindowStyle({
    height: '90%',
    padding-left: '10%'
});

Customizing UI text#

Below is the list of customizable text strings that can be modified.

If an option is not given a custom string, the default value will be used.

Localization#

Customizable strings in customText can be localized. They are contained in an object that has the locale as its key.

var textValues = {
    'en-US': {
        headerText: 'Hello!'
    },
    'fr-FR': {
        headerText: 'Bonjour!'
    }
};

The browser’s language (navigator.language) is used to determine which translation to provide. en-US is the fallback default.

Supported languages#

Change supported languages#

By default, all the languages above are supported by the web chat widget. If you only want to support a specific set of languages, simply include the supportedLanguages field with an array of the language codes you want to continue to support. If the customer’s browser is not in a language that is supported, the widget will default to the fallbackLanguageCode.

NOTE: The fallback language code must be included in the supported languages array

tuliplivechat.init({
    integrationId: '<INTEGRATION_ID>',
    fallbackLanguageCode: 'fr'
    supportedLanguages: ['fr', 'it', 'de']
});

Sample code: customizing strings#

var textValues = {
    'en-US': {
        prechatCaptureGreetingText: 'Please fill out the form to get connected with a fashion advisor.',
        prechatCaptureConfirmationText: 'Thanks for that, so good. We are attempting to find a fashion advisor for you.',
        headerText: 'Haute Couture Inc.'
    }
};

tuliplivechat.init({
    integrationId: '<INTEGRATION_ID>',
    customText: textValues
});

Customize the Contact Us button#

To change the text above the ‘Contact Us’ button, modify the headerMessage key in your custom text overwrites. You can also change the text of the button by changing the contactUsButtonText key.

var textValues = {
    'en-US': {
        headerMessage: 'Custom text above button.',
        contactUsButtonText: 'Click here for service'
    }
};

tuliplivechat.init({
    integrationId: '<INTEGRATION_ID>',
    customText: textValues
});

If you do not want a ‘Contact Us’ button, simply remove the contactUsButtonUrl from the widget configuration. Now, instead of showing the button, we will show the text configured for introductionText.