Web Chat

Embed chat in your website to allow users to ask for help where they need it

Web Chat allows customers to initiate support conversations directly from your website through an embedded chat widget. Conversations automatically appear in your Slack Triage channels where agents can respond, and replies sync back in real-time.

Prerequisite: Email setup is required before configuring Web Chat, as email is used to notify customers when they go offline.

Setting Up Web Chat

Step 1: Complete Email Setup

Web Chat requires email integration for offline notifications. A default ClearFeed Email Address should be pre-configured in your account, if it is not or you want to configure custom Email address, refer here.

Step 2: Enable & Install Chat Widget

  • Navigate to the Settings > Chat Setup on ClearFeed WebApp.

  • Click the toggle to Enable Chat Widget.

  • After enabling the widget, click on Setup Instructions in the same section (Settings > Chat Setup). This page contains your unique client_id and client_secret, along with the necessary code snippets.

  • After enabling the widget, click on Setup Instructions in the same section (Settings > Chat Setup). This page contains your unique client_id and client_secret, along with the necessary code snippets.

  • Add the following script right before the closing <body> tag of your site:

    <script src="https://clearfeed-public.s3.us-east-1.amazonaws.com/chat-widget.js"></script>

  • To securely identify logged-in users and provide them with a personalized, continuous chat history, you need to generate an HMAC hash on your server. This prevents users from impersonating others. (This step is optional and is required only for authenticated users.)

    • Retrieve your unique Client Secret from the Setup Instructions page in the ClearFeed WebApp.

    • Implement server-side code to generate an HMAC-SHA256 hash using your clientSecret and the logged-in user's unique email address.

    const crypto = require('crypto');
// Use your Client Secret obtained from ClearFeed Setup Instructions
const clientSecret = "your_client_secret_here";
// Get the email of the currently logged-in user on your website
const userEmail = currentUser.email; // Replace 'currentUser.email' with how you access the user's email
// Generate the HMAC hash
const userHash = crypto.createHmac('sha256', clientSecret)
    .update(userEmail)
    .digest('hex');

  • Add the initialization script to your website's HTML:.

    • Retrieve your unique Client ID from the Setup Instructions page in the ClearFeed WebApp.

    • Include the user object only when a user is logged into your website. Pass their name, email, and the HMAC hash generated in Step 4. Omit the user object for anonymous visitors.

    <script>
  window.ClearFeed("init", {
    client_id: "your-client-id-here", // Replace with your Client ID

    // Pass user details for signed-in users; omit this 'user' object for anonymous visitors.
    user: userIsLoggedIn ? { // Replace 'userIsLoggedIn' with your logic to check login status
      name: currentUser.name, // Replace with the user's name
      email: currentUser.email, // Replace with the user's email
      hash: userHash // Use the server-generated HMAC hash from Step 4
    } : undefined // Pass 'undefined' or simply omit the 'user' property for anonymous users
  });
</script>

Ensure that the user information (name, email, hash) passed in the user object is not empty when provided.

Understanding User Identification

How ClearFeed Web Chat identifies and handles users depends on the information provided during the widget initialization:

  • Logged-In Users: When you pass the user object containing name, email, and the secure hash for a signed-in user, ClearFeed can reliably identify them. This allows ClearFeed to:

    • Provide a personalized support experience across different devices and browsers.

    • Ensure users can access their past conversation history whenever they return and log in.

  • Anonymous Users: If the user object is omitted during initialization (meaning the visitor is not logged into your website), ClearFeed treats them as an anonymous user. When an anonymous user starts a chat, ClearFeed will automatically prompt them to provide their Name and Email Address before they can begin the conversation. This ensures consistency for their session and allows agents to follow up if needed.

Customizing the Web Chat Widget Appearance and Behavior

You can customize the look and feel of your web chat widget by passing a config object within the window.ClearFeed("init", { ... }) call. This allows for tailoring the widget to match your website's branding and specific needs, even creating different configurations on various pages.

Add the config object as shown below:

<script>
  window.ClearFeed("init", {
    client_id: "your-client-id-here",
    user: userIsLoggedIn ? { /* ... user details ... */ } : undefined,

    // Optional: Customize the appearance and behavior by adding the 'config' object
config: {
brand_color: '#HEXCODE',           // Updates major UI elements like background, icons, input fields, and attachments.
icon_logo_source: 'svg/link',      // Use a direct SVG or a link to your logo.
icon_logo_color: '#HEXCODE' or 'color-name', // Sets color for the default logo, text, and close (X) icon on the web-chat button.
icon_type: "horizontal",           // Options: "horizontal" | "round"
icon_size: "medium",               // Options: "small" | "medium" | "large"
position: "right",                 // Options: "left" | "right"
allow_dragging: true,              // Enables users to drag and reposition the web chat widget.
icon_text: "Help",                 // Label shown next to the icon (applies only for "horizontal" icon_type).
offset: {
    x: 40,                           // Horizontal offset (in pixels) from the left or right edge based on position. Optional (default: 40).
    y: 40                            // Vertical offset (in pixels) from the bottom of the screen. Optional (default: 40).
    }
  }
});
</script>

Configuration Options

Option
Type
Description

brand_color

string

Hex code (e.g., #RRGGBB) to customize primary UI elements like backgrounds, icons, input fields, and attachments.

icon_logo_source

string

A direct SVG string or a URL pointing to your logo image (SVG or other image types supported).

icon_logo_color

string

Hex code or CSS color name to set the color for the default logo, button text, and close (X) icon on the button.

icon_type

string

Determines the appearance of the chat button. Options: "horizontal" (shows text and icon) or "round" (icon only).

icon_size

string

Sets the size of the widget button. Options: "small", "medium", or "large".

position

string

Specifies where the widget button appears on the screen. Options: "left" or "right".

icon_text

string

The label displayed next to the icon when icon_type is set to "horizontal". Ignored for "round" type.

offset

object

Adjusts the button's position: { x: number, y: number } (in pixels). x is horizontal offset from the edge (left or right), y is vertical offset from the bottom.

allow_dragging

boolean

If true, users can drag and reposition the chat widget on desktop. Dragging is limited to stay on-screen.

All web chat widget configuration must be done manually by modifying the initialization script code. There is no user interface within the ClearFeed WebApp for changing these visual or behavioral settings.

Configure Reply Expectations

Define what response time customers see on your chat widget during business hours. Outside of business hours, ClearFeed automatically displays when your team will be back online.

Option
Message Shown to Customers

In a few minutes

“We usually respond within a few minutes.”

In a few hours

“We usually respond within a few hours.”

In a day

“We usually respond within a day.”

Average First Response Time

Displays your average response time based on recent chats.

Web Chat Collection

A Collection "Web Chat" would be automatically created where all the web chat conversations would be routed. You can configure the Collection Settings if required.

FAQs

  1. Is Email setup mandatory for Web Chat? Answer: Yes. Email integration is required to notify customers when they go offline and to send conversation history.

  2. Can I customize the widget appearance? Answer: Yes. Configure widget colors, position, branding etc. in the Web Chat settings. Refer here to see the details

  3. How are chat conversations routed to Slack? Answer: Conversations are routed based on the Web Chat Collection configuration. Each Collection can be associated with a specific Triage channel.

PreviousEmailNextCustomer Portal

Last updated