Webchat

Embed 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. See General Settings below for the full breakdown of each field.

Customize Layout Settings

Configure the widget's appearance and behavior across different sub-tabs. Each is covered in detail in Layout Settings.

Save and Preview

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

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.

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.

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

User Pre-Authentication

When end user authentication 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.

<script> 
    window.HBFWebchat.setAuthToken('<botDiv>', '<token>', '<refresh-token>');
</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 and optional image when the widget first loads, useful for greeting visitors, showcasing promotional banners, 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 and an image. You can chain multiple notifications together by adding a new one again.

Notification text

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

Image

Attach an image to display alongside the notification text. Upload a new file, select one from Media Manager, or paste an external URL. Hover the thumbnail to swap or delete it.

Image Links To

Optional URL opened in a new tab when the visitor clicks the image. The field stays disabled until an image is added.

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.

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

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.

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:

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.

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.

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.

Speech

The Speech tab adds spoken conversation to your Webchat deployment, enabling speech-to-text and text-to-speech for visitors. Toggle Enable Speech to turn voice features on. When disabled, the microphone button is hidden from the widget.

For finer control over the speech experience, the Custom Settings exposes further options, such as routing speech token requests through your own backend and refining how dictated speech is transcribed.

Speech Credentials

Choose which Azure Speech credentials run this deployment:

Helvia (global credentials): Use Helvia's default Azure Speech subscription. No setup required.
Custom Integration: Use your own Azure Speech integration from Workspace > Integrations.

TTS Voice

Set the text-to-speech voice the agent uses (e.g., en-US-JennyNeural). Pick a voice that fits your audience and brand.

For deployments that need to route token requests through their own backend, see azureSpeechTokenURL under Custom Settings and reach out to our support team to wire it up.

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.
// Icon should have ratio 1:1 and width 20px
{
  "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>"
  }
}

// Provide custom Azure Speech Service token retrieval endpoint in case you don't want the
// default one (hbf-core - with Helvia's API keys) to retrieve and provide one
// Add `azureSpeechSynthesisDeploymentId` if the token is bound to a specific                                                        
// deployment (e.g. a Custom Neural Voice); an invalid id will break TTS.    
{
    "azureSpeechTokenURL": "<YOUR_ENDPOINT>"
    "azureSpeechSynthesisDeploymentId": "<YOUR_DEPLOYMENT_ID>"
}

// Edit header styles for Bubble Widget. Those properties provide the ability to 
// console users to add a pill-like style for bubble widget header.
{
    "widgetStyleSet": {       
        "header": {
            "headerBorderRadius": "30px", 
            "headerMargin": "8px 8px 0 0",
            "headerHeight": "70px"
        }
    }
}

// Edit the bubble icon (for bubble widget):
// Set the icon that triggers bubble to open and/or to close.
// Edit the padding
// Edit the animation that the bubble has when closed.
// Adjust the sonar border width (set 0 for an edge-to-edge button)
// Can edit the hover aninamation of the bubble
// Inline SVG values are sanitized; image URLs must be http(s) or data:image/*.
{
    "widgetStyleSet": { 
        "fabIconOpen": string (url of an image or an svg),
        "fabIconClose": string (url of an image or an svg),
        "fabIconPadding": number,
        "fabButtonBorder": number | string,
    /**
     * Object-form is retained so legacy `pulse` can be mapped into a single modern field at config-load.
     * `durationMs` is only supported for `bounce` in v1; `iterationCount` applies to both variants.
     */
        "fabAnimation": {
              "variant": "pulse" | "bounce" | "none",
              "durationMs": number,
              "iterationCount": number | "infinite"
          },
        "fabHoverAnimation": "zoom" | "none",
        "fabOpenCloseIconAnimation": "rotate" | "none"  
    }
}

// Edit the listening overlay layer. You can edit the border-radius, 
// the margin it has from the container and the background color you wish.
{
  "styleSetOptions": {
      "listeningOverlayBackgroundColor": string,
      "listeningOverlayBorderRadius": string,
      "listeningOverlayMargin": string
  }
}

//Create custom Speech-to-Text cleanup rules with these four simple settings:
//1.Find This (match): The spoken words or pattern to look for (e.g., use u\s*s\s*a to ignore spoken spaces).
//2.Replace With (replacement): The clean, official text you want to display in the final transcript (e.g., USA).
//3.Ignore Casing (flags): Type i here to match both lowercase and uppercase versions of the word.
//4.Standalone Word (wholeWord): Keep turned on (true) so it only replaces exact words and doesn't scramble parts of larger words.
{
    "sttReplacements": [
        {
            "match": "<regex_rule>"
            "replacement": "<string_to_replace_regex_above>",
            "flags": "i",
            "wholeWord": true | false
        }
    ],
    ...
}

//Applies a blur to and disables the sendbox when a 
//startup notification is shown.
{
    "startupNotificationsRequireDismissal": true
}

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 17 days ago