Webchat

Deploy your agent as a chat widget on any website

Webchat is the fastest way to put your agent in front of users. Embed a JavaScript snippet on your site and visitors get an interactive chat widget — no backend work required. Despite the simplicity of deployment, Webchat offers the deepest customization of any channel: colors, avatars, bubble behavior, notifications, and more.

How Webchat Works

A Webchat deployment generates a JavaScript snippet. Paste it into your website's HTML and the widget loads automatically. Every visitor gets their own conversation session, and the agent responds using the workflow you assign to the deployment.

You can run multiple Webchat deployments for the same agent — each with different settings, workflows, or branding — to serve different pages or audiences.

Creating a Webchat Deployment

Select the Webchat Channel

Go to Designer > Deployments and click the Webchat icon in the channel toolbar.

Configure General Settings

Give your deployment a Name and optional Description so your team can identify it later. Set the Language the agent will use in conversations, and toggle Enable User Language Detection if you want the widget to adapt to the visitor's browser language automatically. Finally, select the Flow — this is the Start workflow the agent runs when a conversation begins.

Customize Layout Settings

Configure the widget's appearance and behavior across seven sub-tabs: General, Avatars, Colors, Start Up Notifications, Idle Notifications, Actions, and Custom. Each is covered in detail below.

Save and Preview

Click Save Changes. Next, preview the deployment or inspect the JavaScript snippet.

Deleting a Webchat Deployment

Open the deployment's General Settings and click Delete Deployment. Confirm the action by typing "DELETE" in the dialog that appears.

Permanent Action Deleting a deployment is permanent. Clone the deployment first if you want to preserve its configuration.

Embed and Preview

Each Webchat deployment has two options for interacting with the widget:

JavaScript Snippet

Reveals the JavaScript snippet for this deployment. Copy and paste it into your website's HTML along with the to embed the widget.

Use this when you're ready to go live or want to test the widget in a staging environment alongside your actual site content.

Preview

Opens a live preview in a new browser tab. The widget renders on a blank page exactly as visitors will see it.

Use it to quickly verify colors, avatars, notifications, and conversation flow without touching your site.

You can access both the JavaScript Snippet and the Preview from two places: the action icons in the Deployments list, or the buttons inside the deployment's edit dialog.

The JavaScript Snippet consists of two parts, both required for a correct deployment:

The Webchat library script in the page <head>

<script
    src="https://cdn.helvia.io/hbf-webchat/lib/latest-stable/webchat.min.js">
</script>

An initialization script in the page <body>

<div id="botDiv"></div>
  <script> 
    window.HBFWebchat.init( 
      {
        "deploymentId":"<deploymentIdentifier>",
        "apiUrl":"https://core-v5.helvia.io/",
        "entryPoint" : "<flow_start_node_id>" // optional
      }
    );
  </script>

The JavaScript snippet already includes your <deploymentIdentifier>.

Advanced Integration

The Webchat widget exposes JavaScript hooks and HTML attributes that let developers customize user tracking, trigger workflows from page elements, and control widget behavior beyond the visual settings. These features require basic knowledge of HTML and JavaScript.

User identification

Webchat stores a user ID in the browser's localStorage to recognize returning visitors on the same browser and device.

By default, Webchat generates a random user ID. To use your own identifier — for example, to link conversations to authenticated users — implement window.HBF_retrieveUserId() in your site's JavaScript. Webchat calls this function on load and uses the returned value instead.

To pass additional user metadata (name, email, or custom attributes), implement window.HBF_retrieveUserInfo(). Webchat calls this function alongside HBF_retrieveUserId() and attaches the returned data to the contact record.

Hook

Return Type

Purpose

window.HBF_retrieveUserId()

string

A stable, unique identifier for the current user

window.HBF_retrieveUserInfo()

object

A key-value map of additional user information (commonly under customData)

Both hooks are optional. If neither is implemented, Webchat falls back to a randomly generated ID with no additional metadata.

Example: Provide a known user ID and custom data.

<script>
    window.HBF_retrieveUserId = function() {
        return "[email protected]" // replace with actual user's unique identifier
    }
</script>

<script>
    window.HBF_retrieveUserInfo = function() {
        return {
            name: "John Doe",
            email: "[email protected]",
            customData: {
                "<variableName1>": "<variableValue>",
                "<anotherVariable>": "<anotherValue>"
            }
        }
    }

</script>

Reload widget

In order to reload the Webchat widget, without reloading the hosting page, you must first remove the HBFWebchat instance and then initialize it again.

<script>
 window.HBFWebchat.remove();
 window.HBFWebchat.init( 
   {
      "deploymentId":"<deploymentIdentifier>",
      "apiUrl":"https://core-v5.helvia.io/"
   }
 );
</script>

Conversation transcript

You can fetch the whole conversation transcript using the function window.HBFWebchat.getTranscript()

The returning value will be an array of objects with the following interface:

[
  {
   text: string;
   from: { email?: string; name?: string; role: "bot" | "user" };
   timestamp: Date;
  }
]

Trigger workflow via HTML element

Add the attributes class="btn-hcn", data-hcn, and data-target-div to any HTML element to trigger a workflow on click. Set data-hcn to the ID of the start node for the workflow you want to run.

<button type="button" class="btn-hcn" data-lang="el" data-hcn="flowID" data-target-div="botDiv">Start Chat</button>

Trigger workflow with parameters

Use window.HBFWebchat.redirectChatTo() to redirect the widget to a specific node while passing optional variables. These variables are accessible through the parameters object in the platform. If the bubble widget is not open yet, this function opens it automatically and overrides any other configuration.

<button onclick="window.HBFWebchat.redirectChatTo('botDiv', { nodeId:'node-id', variables: { key: 'value' } })">Button label</button>

Trigger workflow via URL query parameters

If your page already has the Webchat widget installed, you can construct links that open the widget and trigger a specific workflow using query parameters.

Parameter

Effect

?hws=on

Opens the widget on page load

?hws=alwayson

Opens the widget and hides the close button

?hcn=<nodeId>

Triggers the workflow starting from the specified node ID

Combine parameters as needed. For example, if https://helvia.ai includes a Webchat widget , the link https://helvia.ai?hws=on&hcn=start opens the widget and starts the workflow with node ID start.

Layout Settings

Webchat is the most customizable deployment channel on the platform. From colors and avatars to notification timing and bubble behavior, Layout Settings give you full control over how the widget looks and acts on your site. Settings are organized into seven distinct tabs.

Brand Matching

Set colors, fonts, and avatars so the widget feels native to your site

Proactive Engagement

Configure automatic pop-outs, chat prompts, and notifications to initiate conversations with visitors

Flexible Layout

Choose between a floating bubble or a full-page embedded chat, and adjust dimensions and corner radius

Advanced Control

Add persistent menu buttons, control file uploads, and inject custom JSON settings for developer-level overrides

Click View Example in any Layout Settings tab to open an annotated diagram of the widget in bubble mode. The diagram labels every customizable area — header, avatars, bubble colors, typing indicator, menu buttons, and more — so you can identify which setting controls which part of the interface before making changes.

General

These settings define the widget's structure and how it fits into your site, starting with the choice between a floating Bubble or a full-page Embedded layout.

Setting

Description

Mode

Bubble renders the widget as a floating button in the bottom-right corner that expands on click. Embedded renders the widget inline as a full-page chat — useful for dedicated support pages.

Widget Radius

Controls the corner curvature of the chat window (0 px for sharp corners, up to 32 px for rounded).

Widget Width / Height

Sets the dimensions of the expanded chat window in pixels. Only available in Bubble mode.

Header Style

Choose between a left or center header bar at the top of the chat window.

Agent Header

The text displayed in the chat window header. This is what visitors see, so pick something approachable.

Font Family

The typeface used inside the widget. Match it to your site's typography for a seamless look.

Link Behavior

Control whether links and link buttons sent by the agent open in the same tab or a new tab. Opening in a new tab keeps the conversation visible.

You can select alternative fonts in case the primary one is not supported by the system of the end-user. If the host website loads custom fonts, the widget can use those too.

Start Up Notifications

Start up notifications display a message when the widget first loads — useful for greeting visitors, announcing promotions, or nudging users toward a specific workflow. Notifications appear in front of the conversation messages and stay visible until the visitor dismisses them or clicks one of the attached buttons.

Click Add Notification to configure a notification. Each notification has a text message and it can display up to three buttons. You can chain multiple notifications together by adding a new one again — they display in sequence when the widget loads.

Notification text

The notification message shown to the user. Make sure not to overwhelm the user with long messages.

Enable Buttons

Attach one, two or three buttons to turn a passive notification into an interactive entry point. Each button has a Button Name (the label visitors see) and a Flow (the workflow triggered on click). For example, a "Talk to Sales" button can route users directly into a sales qualification workflow.

Delete

Delete the notification immediately from the chain using the delete icon .

Idle Notifications

Idle notifications re-engage visitors who opened the widget but stopped interacting. They share the same core settings as start up notifications (text, optional buttons, adding and removing) but offer additional controls: a delay before the notification appears, a sound toggle to grab attention, and the ability to automatically trigger a workflow when the idle threshold is reached.

Idle notifications disappear automatically once the visitor starts typing. Use them to recover abandoned conversations — a message like "Still have questions? I'm here whenever you're ready" can prompt users to resume the chat.

Notification delay

Set how many seconds of inactivity must pass before the notification appears. A shorter delay (e.g., 10 seconds) works for quick support prompts, while a longer delay (e.g., 60 seconds) avoids interrupting users who are still reading. You can type the amount of delay you want or use the , buttons for increments of 10.

Play sound

Toggle a sound effect that plays when the idle notification appears. This adds an audible cue alongside the visual notification, useful for visitors who have scrolled away or switched tabs.

Advanced settings

Automatically start a workflow when the idle threshold is reached. Instead of just showing a notification, the agent can proactively send a message, ask a question, or begin a guided flow — turning inactivity into an opportunity to re-engage the visitor. Select the workflow you want to trigger from the dropdown.

Avatars

Avatars give the conversation a human feel and reinforce brand identity.

Agent Avatar: Upload an image, select from your Media Library, or provide a URL for the icon that appears next to the agent's messages
User Avatar: Same options for the visitor's icon

Both are optional. If no avatar is set, the widget displays a default icon. Any new image you upload is automatically saved to your Media Manager for reuse across other deployments.

Colors

Match the widget to your brand palette. Each field accepts a hex color value or use the color picker to select one visually.

Setting

What It Controls

Main Color

The widget header and primary accent

Main Font Color

Text in the header and primary UI elements

Hyperlink Color

Clickable links inside messages

Chatbot Bubble Color

Background of the agent's message bubbles

Chatbot Bubble Text Color

Text inside the agent's message bubbles

User Bubble Color

Background of the user's message bubbles

User Bubble Text Color

Text inside the user's message bubbles

Test color combinations for accessibility. Ensure sufficient contrast between bubble background and text colors so messages remain readable.

Actions

Actions control how the widget behaves before and during a conversation.

Action Layout determines how the agent presents interactive elements like buttons:

Stacked: Buttons arranged vertically
Carousel: Buttons displayed in a horizontal scrollable row
Flow: Buttons follow the workflow's native layout

Bubble Action controls what happens to the bubble when the page loads (Bubble mode only):

The widget stays collapsed until the visitor clicks it. Use this for pages where the chat should be available but not intrusive.

Additional toggles:

Hide Upload Button

Prevents visitors from uploading files. Enable this if your agent does not process attachments.

Hide Emoji Button

Removes the emoji picker from the input bar.

Hide Typing Indicator

Hides the "typing..." animation while the agent processes a response.

Custom

Toggle Enable Custom Settings to pass additional configuration as raw JSON. This is an advanced option for developers who need to inject custom attributes or override default behavior beyond what the visual settings offer. A validation check ensures the input is valid JSON before you can save changes.

Below is a reference of all available custom settings you can pass to the widget. Each entry includes a comment describing its functionality followed by the corresponding JSON object.

// Hide bot avatar
{
  "styleSetOptions": {
    "botAvatarInitials": null
  }
}

// Hide user avatar
{
  "styleSetOptions": {
    "userAvatarImage": null,
    "userAvatarInitials": null
  }
}

// Add language buttons
{
  "widgetStyleSet": {
    "hcnButtons": [
      {
        "conversationNodeId": "izkhd1",
        "title": "English",
        "language": "en"
      },
      {
        "conversationNodeId": "izkhd1",
        "title": "Ελληνικά",
        "language": "el"
      }
    ]
  }
}

// Set the chatbot's sub-header, while replacing the "powered by helvia.ai"
// Note: Probably need to add also "backgroundColor": "#FCB827" because
// the main color, also used in header get's overwritten
{
  "widgetStyleSet": {
    "header": {
      "subtitleText": "This is a subheader"
    }
  }
}

// Disables the user input when cards are present
{
  "disableSendBoxOnCards": true
}

// Disables the user input when suggested actions are present
{
  "disableSendBoxOnSuggestedActions": false
}

// Stores the session transcript in the browser, that can be accessed
// with "window.HBFWebchat.getTranscript()"
{
  "keepTranscript": true
}

// Bot Avatar inside chat (size)
{
  "styleSetOptions": {
    "avatarSize": 32
  }
}

// Limiting consecutive messages in miliseconds
{
  "disableSendBoxAfterMessageDuration": x
}

// Disables the sendBox at webchat initialization
{
  "disableSendBoxOnStart": true
}

// Show the language selector in the header
{
  "showLocaleSelector": true
}

// Send reminders when user is idle
// Note: the trigger time of each message is independent and it doesn't
// sum. So if you want to show a message after x seconds and another one
// after additional y seconds then you must configure the first for x sec
// and the second for x+y sec.
{
  "idleReminderMessages": [
    {
      "conversationNodeId": "idle-node",
      "triggerWhenInactiveFor": 500
    },
    {
      "quick": [
        {
          "type": "message",
          "text": "It's been an hour since we talked, are you still there?"
        }
      ],
      "triggerWhenInactiveFor": 3600
    },
    {
      "quick": [
        {
          "type": "message",
          "text": "Are you still there?",
          "suggestedActions": {
            "actions": [
              {
                "type": "imBack",
                "title": "Yes",
                "value": "Yes"
              },
              {
                "type": "imBack",
                "title": "No",
                "value": "No"
              }
            ]
          }
        }
      ],
      "triggerWhenInactiveFor": 1800
    }
  ]
}

// Show notifications when user is idle (notifications in the UI)
// Note: the trigger time of each notification is independent and it
// doesn't sum. So if you want to show a notification after x seconds
// and another one after additional y seconds then you must configure
// the first for x sec and the second for x+y sec.
{
  "idleNotifications": [
    {
      "text": "This is just a reminder text. Sent after 10 seconds.",
      "triggerWhenInactiveFor": 10,
      "hasSound": true,
      "level": "info",
      "buttons": [
        {
          "type": "hcn",
          "title": "<Button Title 1>",
          "conversationNodeId": "<Put here the ID of the START NODE of a Flow>"
        },
        {
          "type": "hcn",
          "title": "<Button Title 2>",
          "conversationNodeId": "<Put here the ID of the START NODE of another Flow>"
        }
      ]
    },
    {
      "text": "This is another reminder. Sent after 20 seconds.",
      "triggerWhenInactiveFor": 20,
      "triggerConversationNodeId": "[OPTIONAL] <Put here the ID of the START NODE of a Flow>",
      "hasSound": true,
      "level": "info"
    }
  ]
}

// Show notifications on WebChat Start Up
{
  "startUpNotifications": [
    {
      "text": "First notification text on webchat load with Actions.",
      "level": "info",
      "buttons": [
        {
          "type": "hcn",
          "title": "Button Title 1",
          "conversationNodeId": "Put here the ID of the START NODE of a Flow"
        },
        {
          "type": "hcn",
          "title": "Button Title 2",
          "conversationNodeId": "Put here the ID of the START NODE of another Flow"
        }
      ]
    },
    {
      "text": "Second notification text on webchat load without Actions.",
      "level": "info"
    }
  ]
}

// Change the colors of the INFO level Notifications
{
  "styleSetOptions": {
    "toastInfoBackgroundColor": "blue",
    "toastInfoColor": "white"
  }
}

// Enables chat message history.
// Note: Setting maxNumberOfSessions to 0 stores all of the sessions
// and setting maxNumberOfMessages to 0 is akin to disabling the feature.
{
  "messageHistory": {
    "enabled": true,
    "sendGreetingMessage": false,
    "maxNumberOfMessages": 15,
    "maxNumberOfSessions": 1
  }
}

// Maximum File Size for Upload in Bytes (max allowed: 4194304 bytes)
// & Node ID to get triggered when the file size was exceeded
{
  "maxFileSizeForUpload": 4194304,
  "fileTooLargeConversationNodeId": "uploaded-large-file"
}

// Whether to enable file upload only when channelData has isFileUpload = true
{
  "enableFileUploadOnDemand": false
}

// Whether to keep the buttons within adaptive cards enabled after they
// are clicked.
// Note: If there are inputs in the card, the button is considered a
// "submit" type button, and is thus always disabled, even if the
// setting is true.
{
  "keepCardButtonsEnabledAfterClick": false
}

// Whether to enable sound notifications for webchat messages received
// from bot.
// If set to "all" then a sound will be triggered for all messages received.
// If set to "livechat" a sound will be triggered *only* for livechat
// messages received.
// If "messageSoundNotifications" is not set at all (omitted) then there
// will be no sounds triggered on webchat.
{
  "messageSoundNotifications": "all" | "livechat"
}

// Style CSAT popup
{
  "styleSetOptions": {
    "csatFontFamily": "Arial",
    "csatFontSize": 16,
    "csatMainColor": "#2bbdc2",
    "csatButtonFontColor": "white"
  }
}

// Rounded webchat bubbles and buttons
{
  "styleSetOptions": {
    "bubbleBorderRadius": "30px",
    "suggestedActionBorderRadius": "30px"
  }
}

// Sendbox to wrap the text
{
  "styleSetOptions": {
    "sendBoxTextWrap": true
  }
}

// Enable / disable home icon in textbox.
// By clicking on the home icon button the initial flow is triggered.
{
  "styleSetOptions": {
    "sendBoxHomeActionButtonEnabled": true,
    "sendBoxHomeActionButtonIconUrl": ""
  }
}

// Enable / disable custom action icon in textbox.
// By clicking on the custom action icon, the node id noted in
// sendBoxCustomActionButtonTriggerNodeId will be triggered.
// The default icon is a livechat icon
{
  "styleSetOptions": {
    "sendBoxCustomActionButtonEnabled": true,
    "sendBoxCustomActionButtonTriggerNodeId": "",
    "sendBoxCustomActionButtonIconUrl": ""
  }
}

// Customize carousel cards and arrows.
// Note: For bubble widget, if the widget width is less than 410px, then
// we ignore the "carouselCardWidth" and "carouselCardSpacing" and enforce
// their values in order to have the widget work and carousel style work
// properly.
{
  "styleSetOptions": {
    "carouselCardWidth": 275,
    "carouselCardSpacing": 45,
    "carouselTextColor": "#000000",
    "carouselCardBackgroundColor": null,
    "carouselArrowBackgroundColor": "#ffffff",
    "carouselArrowColor": "#000000",
    "carouselArrowHoverBackgroundColor": "#000000",
    "carouselArrowHoverColor": "#ffffff"
  }
}

// Enable pre chat steps
// Note: If "deployments" is missing, then we skip the whole step 2
// and we redirect to the webchat deployment directly.
{
  "widgetStyleSet": {
    "advancedChatPromptBubble": {
      "enable": true,
      "stepOneMessage": "This is a custom setting message",
      "stepOneButtonLabel": "Custom label",
      "stepTwoMessage": "Second custom message",
      "deployments": [
        {
          "url": "",
          "icon": "https://example.com/icon1.png"
        },
        {
          "url": "fb-messenger://",
          "icon": "https://i.postimg.cc/SxSjK2z7/messenger.png"
        }
      ]
    }
  }
}

// Manage bubble widget width and height
// Note: If width and height is set from custom options it will override
// the values set in the console general settings.
{
  "widgetStyleSet": {
    "width": "400px",
    "height": 1200
  }
}

// Send an event when the user closes the webchat window/tab
{
  "sendUserLeftEvent": true
}

// Change the send icon of webchat
{
  "styleSetOptions": {
    "sendBoxSendIcon": "<svg ...></svg>"
  }
}

// Change end-livechat-confirmation text
{
  "styleSetOptions": {
    "terminateLivechatConfirmation": "Are you sure?"
  }
}

// Enable STT TTS
{
  "allowSpeechToText": true
}

// Change microphone's icon color
{
  "styleSetOptions": {
    "sendBoxMicrophoneButtonColorOnListening": "<COLOR_SELECTION>"
  }
}

If you need multiple custom settings, merge them into a single JSON object. Do not paste separate JSON blocks, otherwise it is not going to pass the validation check. Combine all keys under one root object instead.

Best Practices

Match your brand: Use your brand colors, fonts, and a recognizable avatar so the widget feels native to your site, not bolted on
Start with Bubble mode: Most websites benefit from a non-intrusive floating widget. Reserve Embedded mode for dedicated support or help pages
Use Chat Prompt over Automatic Pop-out: A subtle prompt message respects the visitor's attention more than a full widget opening unprompted
Keep start up notifications concise: One short message with a clear call-to-action outperforms a wall of text
Preview before deploying: Always use the eye icon to test changes before updating the snippet on your live site

You now know how to create, customize, and embed a Webchat deployment on your website.

PreviousDeployments NextThird-Party Channels

Last updated 1 day ago

Was this helpful?

hashtagHow Webchat Works

hashtagCreating a Webchat Deployment

hashtagSelect the Webchat Channel

hashtagConfigure General Settings

hashtagCustomize Layout Settings

hashtagSave and Preview

hashtagDeleting a Webchat Deployment

hashtagEmbed and Preview

hashtagcode

hashtagJavaScript Snippet

hashtageye

hashtagPreview

hashtagAdvanced Integration

hashtagLayout Settings

hashtagpalette

hashtagBrand Matching

hashtagcomments

hashtagProactive Engagement

hashtagtable-layout

hashtagFlexible Layout

hashtaggears

hashtagAdvanced Control

hashtagGeneral

hashtagStart Up Notifications

hashtagIdle Notifications

hashtagAvatars

hashtagColors

hashtagActions

hashtagCustom

hashtagBest Practices

How Webchat Works

Creating a Webchat Deployment

Select the Webchat Channel

Configure General Settings

Customize Layout Settings

Save and Preview

Deleting a Webchat Deployment

Embed and Preview

JavaScript Snippet

Preview

Advanced Integration

Layout Settings

Brand Matching

Proactive Engagement

Flexible Layout

Advanced Control

General

Start Up Notifications

Idle Notifications

Avatars

Colors

Actions

Custom

Best Practices