search

message-linesWeb 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.

circle-info

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

hashtag
Setting Up Web Chat

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

hashtag
Step 2: Enable & Install Chat Widget

  • Navigate to the Settings > Chat Setuparrow-up-right 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://cdn.clearfeed.app/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>
triangle-exclamation

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

hashtag
How User Identity Appears in ClearFeed

Currently, the ClearFeed WebApp does not provide a dedicated, clickable "User Profile" view (e.g., to open a panel showing email/phone) for Web Chat requesters. Instead, the requester identity shown in ClearFeed is derived from the `user` object you pass when initializing the widget. If you want agents to see additional metadata such as email or phone directly in the requester name shown across ClearFeed interfaces, you can embed that information into the `name` field you send from your website.

hashtag
User Identity Updates and Limitations

  • Name updates after initialization: If a user changes their name (for example, in your application or identity provider) and then starts a new Web Chat session / creates a new ticket, the updated name will be reflected in ClearFeed for that new ticket.

  • Existing tickets: Tickets that were already created before the name change will continue to show the original name captured at the time of ticket creation. Historical tickets are not retroactively updated.

  • Display length limit: In Slack triage channels, the user name is truncated to 50 characters. Names longer than 50 characters will be trimmed in the triage message.

  • Additional user parameters: During window.ClearFeed("init", { ... }), the user object currently supports only name, email, and hash. Passing additional custom parameters in the user object is not supported at this time and such values will not appear on the ticket.

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

circle-info

Web chat widget does not support session invalidation, logout, or a session reset.

hashtag
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:

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

circle-exclamation

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.

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

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

hashtag
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