Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Email Behavior Configuration

By default, when customers go offline during a web chat conversation, ClearFeed sends email notifications to keep them informed about responses and conversation updates. This email behavior can be configured:

  • Email Push Delay — Controls the delay before email notifications are sent when a customer goes offline

  • Disable Email When Offline — Option to disable email sending from web chat when the requester is offline

When email notifications are disabled, customers will only see updates when they return to the web chat widget and come back online. Contact ClearFeed support to configure these email behavior settings for your account.

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.

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

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

Test the Chat Widget

Admins and Managers can test the widget from Settings > Chat Setup without installing it on a site. Click Test chat widget and select a scenario — Business hours or Outside business hours — to see how the matching status message appears to visitors. You can also send test messages and attachments.

Pass custom field values from your website

Use the optional host_fields object to add context from your website to new Web Chat requests. It works for both identified and anonymous visitors. Add host_fields next to user in the initialization payload.

The keys are custom field IDs. The values depend on the field type:

To find and copy field and option IDs:

  1. Go to Forms → Fields.

  2. Turn on Show API IDs.

  3. Click a field ID or option tag to copy its ID.

See Custom Fields for more information about API IDs.

Supported values

Field type
Value

Single Select

Option ID as a string

Multi Select

Array of option IDs as strings

Single-Line Text

String within the field's character limit

Multi-Line Text

String within the field's character limit

Number

Integer or decimal number

Date

Date string in YYYY-MM-DD format

User Select

Email address of a user in the account's workspace

You can pass up to 50 fields in one initialization payload.

ClearFeed applies these values when it creates a request, before routing, automations, assignment rules, and SLA calculation. Successfully applied values appear in the WebApp activity feed as updates made by Web Chat. Existing requests are not updated.

If a field ID or value is unusable, ClearFeed skips that field and creates the request without it. For Multi Select fields, valid option IDs are applied even if other option IDs in the same value are unusable. Skipped fields do not appear in the activity feed, and the visitor does not see an error.

host_fields values are not signed. A visitor can alter them in the browser before submitting a request. Because ClearFeed applies the values before routing and automations, altered values can affect assignment, automation, and SLA behavior. Do not use host_fields for security-sensitive or trusted values.

How User Identity Appears in ClearFeed

The requester identity shown in ClearFeed comes from the user object passed during widget initialization. The ClearFeed WebApp does not provide a separate clickable profile for Web Chat requesters. Keep identity information in name and email. Use host_fields for additional structured context.

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: The user object supports only name, email, and hash. Put custom field values in the sibling host_fields object.

Conversation Titles in Web Chat

For newer Web Chat tickets, ClearFeed automatically generates a title for the conversation. This title appears in the conversation list view and helps users quickly identify the topic of each chat.

How Conversation Titles Appear

In the conversation list view, each chat session displays:

  • First line: The conversation title in bold, with the timestamp right-aligned next to it

  • Second line: A message preview showing the last message from the conversation

    • If a responder has replied: Shows SenderName: message preview (truncated)

    • If no responder message exists: Shows just the message preview

When Titles Are Generated

  • Conversation titles are automatically generated from the content of the conversation

  • If the conversation starts with an ignorable greeting (like "Hi"), no title is generated initially

  • When a meaningful user message is sent later, a title is generated from that message

Customize Email Subjects for Offline Notifications

By default, notification emails use the Web Chat conversation title as the subject. Admins can instead set a custom subject template. The first email subject is preserved across subsequent replies to keep the email thread consistent.

To set a custom subject:

  1. Go to Settings > Chat Setup.

  2. Turn on Custom Email Subject.

  3. Enter a subject template. Use the insert buttons to add a supported placeholder anywhere in the subject.

  4. Click Save.

For example, use Re. your issue of {{ticket.title}}.

Placeholder
Value

{{ticket.title}}

The Web Chat ticket title

{{ticket.id}}

The Web Chat ticket ID

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.

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

Conversation Lifecycle and Ticket Status

Web Chat conversations remain visible even when the corresponding ClearFeed ticket is marked Solved or Closed in the WebApp. This is expected behavior and is designed to:

  • Preserve full conversation history for the end user

  • Allow customers to return and continue the same chat later if needed

Because the widget does not support session invalidation or clearing the chat history, closing a ticket in ClearFeed does not prevent the customer from sending additional messages in the same Web Chat thread.

If you want to clearly communicate resolution or encourage users to start a new chat for new issues, you can use Conversation Status Messages to send an automatic message when a ticket is solved. See Customizing Status Messages for details on configuration options.

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:

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.

text_color

string

Hex code (e.g., #RRGGBB) to customize text color throughout the widget.

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.

When Reply Expectation Messages Are Shown

The reply expectation message follows this logic:

State
Message Displayed
When It Appears

No messages yet

Response time message (configured below) or business hours return time

Before a ticket is created, or when a customer clicks "Start a conversation" but hasn't sent a message

Customer sent message, no responder reply

"Someone is looking into it and will respond shortly."

After a customer sends a message and no responder has replied yet

Responder replied

No message

Once a responder has replied to the ticket

Note: The "Someone is looking into it..." message is not editable and cannot be configured as of now.

These messages are only shown when Virtual Agent interactive mode is disabled. When Virtual Agent interactive mode is enabled, no reply expectation messages are displayed. Learn more.

Configuring Reply Expectations

To configure the reply expectation message:

  1. Navigate to Settings (from the left sidebar in ClearFeed WebApp)

  2. Select Chat Setup

  3. Under the Reply Expectations section, choose your preferred response time option

Response Time Options

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.

Customizing Status Messages

Admins can customize conversation status messages from Settings > Chat Setup. These messages can include the {{response_time}} variable, which uses the value configured in Configuring Reply Expectations.

Two message types are available:

Conversation Status Messages configuration in Chat Setup

  • New Conversation Message — Shown when the chat widget has been opened but no messages have been posted yet (by either the customer or agents). Use this to set reply-time expectations, such as "We typically respond within 2 hours during business hours."

  • Awaiting Reply Message — Shown when the customer has posted a message and is waiting for an agent response. Use this to acknowledge that their message has been received and provide visibility into response timing.

Timing Configuration: You can configure different messages for Within Business Hours and Outside Business Hours to reflect different response expectations based on when the customer reaches out.

Template Variables: Status messages support the following dynamic variables:

  • {{response_time}} — Uses the response time configured in Reply Expectations

  • {{next_available_day}} — Next day when your team is available

  • {{next_available_time}} — Next time when your team is available

Virtual Agent Interactive Mode: The New Conversation and Awaiting Reply status messages above are only shown when Virtual Agent interactive mode is disabled for the collection. When Virtual Agent interactive mode is enabled, neither status message is shown — instead, the widget opens with the Virtual Agent's configured greeting message and continues the conversation via the AI agent. Learn more.

Displaying Business Hours Return Time

If you have configured Business Hours for your Web Chat collection, ClearFeed will automatically display when your team will be back online to customers who reach out outside of those hours.

To set up Business Hours:

  1. Navigate to More → Business Schedule & SLA (from the left sidebar in ClearFeed WebApp)

  2. Create or edit a Business Schedule

  3. Apply it to your Web Chat collection

Sending Automated Greeting Messages

You can configure automated messages to be sent when a query comes through your Web Chat - for example: "Thanks for getting in touch! Our team is looking into it and will get back to you shortly."

Use ClearFeed Automations to set up automated replies triggered on new request creation events.

Web Chat Collection

By default - when a new account is created in ClearFeed - a "Web Chat" collection would be automatically created. Furthermore (for accounts created 2026 and later), logged in conversations are automatically routed to the corresponding Customer Collection (and the conversations started from webchat will show up in the triage channel for that Customer Collection). By default, in new accounts, this channel is named #cf-triage-channel.

Users can:

  • Turn off routing of chat requests to Customer Collections

  • After turning off routing, potentially

These configuration changes can be performed using Settings (top-right) after clicking on the Web Chat Collections.

Showing Solved and Closed Status in Web Chat

ClearFeed can display the Solved or Closed status directly in Web Chat, so requesters know when their issue has been resolved.

This behavior depends on how the request is resolved and how your Web Chat is configured.

When the status is shown

If a responder marks a request as Solved or Closed from the collection:

  • The status is shown in Web Chat only if the Show solved/closed status setting is enabled in Web Chat configuration.

  • If the setting is disabled, the status change is not shown to the requester in Web Chat.

Behavior When Virtual Agent Interactive Mode Is Enabled

When Virtual Agent interactive mode is enabled for the collection, status updates are driven by the Virtual Agent session instead of (or in addition to) the general Show solved/closed status setting:

  • Escalated to a human/ticket: If the Virtual Agent session escalates — either because the requester asked for a ticket, or there was no response for 1 hour — a "Ticket {ticketId} created" message is shown inline in the conversation, right after the message that triggered the escalation.

  • Resolved by the requester: If the requester marks their issue as resolved using the Virtual Agent's own feedback buttons, a "Conversation resolved" message is shown inline at that point in the conversation, regardless of the Show solved/closed status setting.

  • Avoiding duplicate messages: If the Virtual Agent session has already shown its own resolved status inline, the general Solved/Closed status message (from the setting above) is not shown again for the same resolution, to avoid displaying the same status twice.

  • A responder marking the request Closed (as opposed to Solved via the Virtual Agent) still follows the general Show solved/closed status setting described above.

Using ClearFeed Web Chat with a Content Security Policy (CSP)

If your website uses a Content Security Policy, you will need to explicitly allow the domains that the ClearFeed Web Chat widget connects to. Add the following sources to your existing CSP directives:

Why each directive is needed

  • cdn.clearfeed.app — loads the widget JavaScript and serves Web Chat attachments and images

  • api.clearfeed.app — handles Web Chat configuration, user authentication, attachment uploads, and Virtual Agent feedback

  • identitytoolkit.googleapis.com and securetoken.googleapis.com — used for Firebase-based authentication and token refresh

  • *.firebaseio.com (https and wss) — powers live conversation updates. Firebase routes connections through dynamically selected shard hosts, so the wildcard is required rather than a fixed hostname

  • fonts.gstatic.com — serves the Lato font used by the widget

  • style-src 'unsafe-inline' — currently required because the widget injects its styles at runtime

  • d1dgs4iz617thf.cloudfront.net — serves the default ClearFeed and Virtual Agent avatars

  • clrf-prd-va-public.s3.amazonaws.com — serves public Virtual Agent assets

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 have multiple web chat widgets with different credentials or configurations on different websites?

    Answer: No, each ClearFeed account supports only one set of web chat widget credentials (client ID and secret). If you need separate widgets with different credentials or authentication (for example, for different websites or customer installations), you must create a separate ClearFeed account (or child account) for each. Each account will have its own independent credentials and configuration.

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

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

PreviousDKIM Setup for Custom Domain
NextPortal

Last updated