> For the complete documentation index, see [llms.txt](https://docs.helvia.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helvia.ai/deploy/webchat.md). # 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 with 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. Give each its own settings, workflow, or branding to serve different pages or audiences.

Feature	Description
On-Brand Design	Match colors, fonts, and avatars so the widget feels part of your site
Easy Deployment	Drop one JavaScript snippet on any site and the widget loads itself, no backend required
Voice Conversations	Let visitors speak and hear replies with speech-to-text and text-to-speech
Deeply Customizable	Fine-tune layout, behavior, and advanced options through visual settings and custom JSON

### Creating a Webchat Deployment {% stepper %} {% step %} #### Select the Webchat Channel Go to **Designer > Deployments** and click the **Webchat** icon in the channel toolbar. {% endstep %} {% step %} #### Configure General Settings Give your deployment a **Name** and optional **Description** so your team can identify it later. See [#general-settings](#general-settings "mention") for the full breakdown of each field. {% endstep %} {% step %} #### Customize Layout Settings Configure the widget's appearance and behavior across different sub-tabs. Each is covered in [Layout Settings](/deploy/webchat/layout-settings.md). {% endstep %} {% step %} #### Save and Preview Click **Save Changes**. Next, preview the deployment or inspect the JavaScript snippet. {% endstep %} {% endstepper %} ### Embed and Preview Each Webchat deployment has two options for interacting with the widget:

Method	Description
JavaScript Snippet	Reveals the JavaScript snippet for this deployment. Copy and paste it into your website's HTML 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.

Method

Description

JavaScript Snippet

Reveals the JavaScript snippet for this deployment. Copy and paste it into your website's HTML 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 `` ```javascript ``` * An initialization script in the page `` ```html

``` {% hint style="info" %} The JavaScript snippet already includes your ``. {% endhint %} ### Bubble and Embedded Webchat appears on your site in one of two styles. Choose the one that matches how prominent you want the chat to be, then set it with the **General > Mode** option in [Layout Settings](/deploy/webchat/layout-settings.md).

Style	Description
Bubble	A floating launcher button that expands into a chat window, best for general sites and landing pages
Embedded	The chat rendered inline on the page with no launcher button, best for dedicated support and help pages

Style

Description

Bubble

A floating launcher button that expands into a chat window, best for general sites and landing pages

Embedded

The chat rendered inline on the page with no launcher button, best for dedicated support and help pages

### Settings A Webchat deployment is configured through its settings tabs, each covering a different layer of the widget. #### General Settings The General Settings tab controls deployment-level behavior that applies before the conversation begins: | Field | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Language** | The default language the agent uses in conversations. | | **Flow** | The Start workflow the agent runs when a conversation begins. | | **Allowed Origins** | Restricts which domains can embed and load the widget. Add the URL of every site that should host this deployment or use wildcards (e.g., `*.example.com`) to cover subdomains. | {% hint style="info" %} Leave **Allowed Origins** empty during testing to allow all origins. Always set it before going to production so the widget cannot be loaded from sites you do not control. {% endhint %} To remove a deployment, click **Delete Deployment** and confirm 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 %} #### Layout Settings Layout Settings is where you customize how the widget looks and behaves: colors, avatars, notifications, actions, and voice, across a set of visual tabs. See the [Layout Settings](/deploy/webchat/layout-settings.md) page for the full breakdown. #### Custom Settings For configuration beyond the visual tabs, enable Custom Settings inside Layout Settings and pass a JSON object. See the [Custom Settings](/deploy/webchat/custom-settings.md) page for every available key. ### Developer Hooks 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`)

{% 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. ```html ```

User Pre-Authentication

When [end user authentication](/security/end-user-authentication.md) is enabled on an agent, the embedding site can pass a pre-authenticated token so the user enters the conversation already signed in. Use `window.HBFWebchat.setAuthToken(divId, token, refreshToken?)` to set or update the token at runtime. The `divId` is the deployment ID you passed to `HBFWebchat.init()`; it targets the right widget when your page has more than one. The `token` is the pre-authenticated value the platform validates against the providers configured on the agent. The optional `refreshToken` lets the platform refresh expired tokens during the session without prompting the user.\ \ The token can also be supplied at init through `customData.authToken` (and `customData.authRefreshToken` if a refresh is needed). Use this when the user is already authenticated by the time the widget loads. ```javascript ```

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. ```html ```

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; } ] ```

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

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

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

### 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 * **Set Allowed Origins before production:** Restrict which domains can load the widget so it cannot be embedded on sites you do not control * **Preview before deploying:** Always use the eye icon to test changes before updating the snippet on your live site {% hint style="success" %} You now know how to create, customize, and embed a Webchat deployment on your website. {% endhint %}

:palette:

On-Brand Design

:code:

Easy Deployment

:microphone:

Voice Conversations

:sliders:

Deeply Customizable

:code:

JavaScript Snippet

:eye:

Preview

:comment-dots:

Bubble

:table-layout:

Embedded