# Webchat 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 {% stepper %} {% step %} #### Select the Webchat Channel Go to **Designer > Deployments** and click the **Webchat** icon :globe: in the channel toolbar. {% endstep %} {% step %} #### 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. {% endstep %} {% step %} #### 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. {% endstep %} {% step %} #### Save and Preview Click **Save Changes**. Next, preview the deployment or inspect the JavaScript snippet. {% endstep %} {% endstepper %} ### 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. {% hint style="danger" %} **Permanent Action** Deleting a deployment is permanent. Clone the deployment first if you want to preserve its configuration. {% endhint %} ### Embed and Preview Each Webchat deployment has two options for interacting with the widget:
MethodDescription

:code:

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.

:eye:

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 `` ```javascript ``` * An initialization script in the page `` ```html
``` {% hint style="info" %} The JavaScript snippet already includes your ``. {% endhint %} #### 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-question: 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.
HookReturn TypePurpose
window.HBF_retrieveUserId()stringA stable, unique identifier for the current user
window.HBF_retrieveUserInfo()objectA key-value map of additional user information (commonly under customData)
{% hint style="info" %} Both hooks are optional. If neither is implemented, Webchat falls back to a randomly generated ID with no additional metadata. {% endhint %} Example: Provide a known user ID and custom data. 
<script>
    window.HBF_retrieveUserId = function() {
        return "user@example.com" // replace with actual user's unique identifier
    }
</script>

<script>
    window.HBF_retrieveUserInfo = function() {
        return {
            name: "John Doe",
            email: "user@example.com",
            customData: {
                "<variableName1>": "<variableValue>",
                "<anotherVariable>": "<anotherValue>"
            }
        }
    }

</script>
:rotate-right: 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>
:messages: 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: ```javascript [ { text: string; from: { email?: string; name?: string; role: "bot" | "user" }; timestamp: Date; } ] ```
:bolt: 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. ```html ```
:bolt: 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. ```html ```
:bolt: 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=` | 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.
FeatureDescription

:palette:

Brand Matching

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

:comments:

Proactive Engagement

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

:table-layout:

Flexible Layout

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

:gears:

Advanced Control

Add persistent menu buttons, control file uploads, and inject custom JSON settings for developer-level overrides
{% columns %} {% column width="58.333333333333336%" %} 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. {% endcolumn %} {% column width="41.666666666666664%" %}
{% endcolumn %} {% endcolumns %} #### 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.
SettingDescription
ModeBubble 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 RadiusControls the corner curvature of the chat window (0 px for sharp corners, up to 32 px for rounded).
Widget Width / HeightSets the dimensions of the expanded chat window in pixels. Only available in Bubble mode.
Header StyleChoose between a left or center header bar at the top of the chat window.
Agent HeaderThe text displayed in the chat window header. This is what visitors see, so pick something approachable.
Font FamilyThe typeface used inside the widget. Match it to your site's typography for a seamless look.
Link BehaviorControl 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.
{% hint style="info" %} 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. ![](https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2FgVP2CXcLkuZzsbXjoWC6%2FScreenshot%202026-03-10%20at%202.06.52%E2%80%AFPM.png?alt=media\&token=c3144a7e-1894-400f-b9f1-ae053b94e198) {% endhint %} #### 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.
:message-text: Notification text The notification message shown to the user. Make sure not to overwhelm the user with long messages.
:square-check: 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.
:trash-can: Delete Delete the notification immediately from the chain using the delete icon :trash-can:.
#### 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.
:timer: 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 :plus:, :minus: buttons for increments of 10.
:volume: 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.
:arrow-progress: 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.
SettingWhat It Controls
Main ColorThe widget header and primary accent
Main Font ColorText in the header and primary UI elements
Hyperlink ColorClickable links inside messages
Chatbot Bubble ColorBackground of the agent's message bubbles
Chatbot Bubble Text ColorText inside the agent's message bubbles
User Bubble ColorBackground of the user's message bubbles
User Bubble Text ColorText inside the user's message bubbles
{% hint style="info" %} Test color combinations for accessibility. Ensure sufficient contrast between bubble background and text colors so messages remain readable. {% endhint %} #### 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): {% tabs %} {% tab title="No Bubble Action" %} The widget stays collapsed until the visitor clicks it. Use this for pages where the chat should be available but not intrusive. {% endtab %} {% tab title="Automatic Pop-out" %} The widget opens automatically after a set number of seconds. Configure the Pop-out Time to control the delay. Good for landing pages where you want to proactively engage visitors. Additional timing options: * No advanced time settings: Default behavior, automatic pop-out after the configured delay * Double pop-out time after every view: On each page refresh double the configured delay * Pop-out only once: The widget opens once; subsequent page loads keep it collapsed {% endtab %} {% tab title="Chat Prompt" %} Instead of opening the full widget, a small prompt message appears after a set time (e.g., "Need help?"). This is less intrusive than a full pop-out and gives the visitor the choice to engage. Configure the Pop-out Time and set the Chat Prompt Message with the text shown in the chat prompt.
{% endtab %} {% tab title="Advanced Chat Prompt" %} A multi-step prompt that appears when the visitor clicks the bubble icon, before the conversation begins. Use this to greet visitors and route them to different deployments. The interaction has two steps: 1. The visitor clicks the bubble and sees a message with a single button. Configure the text with **Step One Message** and the button label with **Step One Button Label**.
2. After clicking the button, the visitor sees a set of deployment buttons. You can create up to 4 buttons. Each button has a configurable **Deployment URL** and **Deployment Icon**, allowing you to route visitors to different channels (e.g., Webchat, Messenger, WhatsApp). For web deployment the deployment URL should be left empty.
This is useful when you want a single entry point on your site that branches into multiple support channels or specialized agents. {% endtab %} {% endtabs %} Additional toggles:
:paperclip-vertical: Hide Upload Button Prevents visitors from uploading files. Enable this if your agent does not process attachments.
:face-smile: Hide Emoji Button Removes the emoji picker from the input bar.
:comment-dots: Hide Typing Indicator Hides the "typing..." animation while the agent processes a response.
:table-cells-large: Enable Menu Buttons Adds persistent buttons to the widget that trigger specific workflows, regardless of where the user is in the conversation.
#### 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. {% code expandable="true" %} ```javascript // 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": "