Web Chat

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

The ClearFeed Web Chat widget allows you to embed a direct support chat interface on your website, connecting your users with your support team via Slack.

Set Up Guide

  • 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.

  • 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.

    • 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>

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.

Managing the Web Chat Collection

When you enable the Chat Widget, a standard ClearFeed Collection named "Web Chat" is automatically created in your account. All incoming chats from your website will appear as requests within this collection. Below configurations can be done for Chat Collection:

  • Responder Settings – Define who from your organization should be treated as support agents/members in ClearFeed.

  • Triage Channel – Configure the channel for the support team to work from on Slack to handle incoming support requests.

  • Assignment Rules – Define how requests or tickets are assigned, supporting round-robin or rule-based assignment.

  • Ticketing - Select your integration and choose the trigger mode for ticket creation. Trigger mode for the ticket can be an emoji (e.g.. 🎟️) applied to the thread or tickets can be auto-created on every new message on the request channel.

  • GPT-Powered Answers - Enable AI-driven responses for common queries.

  • Automations – Set up workflow automation based on triggers like request creation, status changes, or SLA breaches.

  • Business Schedules & SLA - Define working hours to ensure SLAs are calculated accurately & Configure service level agreements (SLAs) for response and resolution times.

  • Additional Collection Settings - Download request data and customize message classification settings.

Last updated

Was this helpful?