Custom Settings

Fine-tune every part of the Webchat widget with JSON

Custom Settings give you full control over how the Webchat widget looks and behaves. They are a single JSON object that reaches every part of the widget, including options not available through the UI. Almost every key has a default, so you change only what you need.

What Are Custom Settings

Custom Settings are how you fine-tune the Webchat widget beyond the rest of the settings. They are a single JSON object of configuration keys that together control almost every part of the widget: how it connects, how it looks, and how it behaves. Each key controls one option, so you set only the keys you want to change and leave the rest to their defaults.

A few things worth knowing before you start:

Custom Settings take priority

A key you set always wins. It overrides the same option in the Layout Settings, which in turn overrides the widget's built-in default. So Custom Settings have the final say over anything you could also configure in the panels.

Your input is checked as you type

The Custom tab validates your JSON as you edit and blocks saving until the object is valid. If a comma or bracket is missing, fix it before you can save. Paste the object into a JSON validator if you are unsure.

Set several values at once

Combine as many keys as you like into one JSON object. Keys that share a parent go inside the same object; keys with a different parent each get their own.

{
  "locale": "en",
  "widgetStyleSet": {
    "color": "#605dec",
    "header": { "text": "Chat with us" }
  }
}

List settings replace, they do not merge

Most keys take a single value, but a few are lists, such as startUpNotifications, idleNotifications, and greetingMessages. When you set a list, the array you provide replaces the default list entirely instead of adding to it.

Powered by Microsoft Bot Framework Web Chat

The Webchat widget is built on Microsoft Bot Framework Web Chat v4.18. The defaults and behavior on this page reflect Helvia.ai's brand defaults applied on top of that engine.

Applying Custom Settings

You apply Custom Settings through the Custom tab in a Webchat deployment's Layout Settings. Turn on Enable Custom Settings and enter your configuration as a single JSON object.

Per deployment: Custom Settings apply only to the deployment you edit. Each Webchat deployment keeps its own set, so you can give every deployment different settings.

How This Page Is Organized

The reference is split into three sections. Each opens with a commented JSON example, followed by a table of its keys. Every table has four columns: the Key, a Description, the Default applied when you leave the key unset, and an Example value.

Core Settings

Root-level keys that control how the widget connects and behaves

Everything under widgetStyleSet: the launcher, window, header, and pop-ups

Everything under styleSetOptions: colors, fonts, and bubbles inside the chat

Some keys carry an inline tag at the start of their description:

(BLOCKED): Platform-set. You cannot override this key from Custom Settings.
(UI): Also available as a visual option in the Helvia Console, so you rarely need to set it by hand.
(DEPRECATED): Kept only for backward compatibility. Avoid it in new setups.

A Default of not set means the key has no value until you provide one. A Default of required means the key must be present whenever you use its parent setting.

Core Settings

Core settings sit at the root of the JSON object. They cover how the widget connects and how it behaves during a conversation.

A core settings block at a glance:

{
  // ── Identity & connection ──  ("id" and "tokenURL" are BLOCKED: platform-set)
  "azureSpeechTokenURL": "https://…/speech",        // empty string is ignored
  "azureSpeechSynthesisDeploymentId": "deploy-123",
  "domain": "https://europe.directline.botframework.com/v3/directline",
  "secret": "abc123",                                // enables setting `bot` below
  "bot": { "id": "bot-001", "name": "Support Bot", "role": "bot" },  // BLOCKED unless `secret` set
  "user": { "name": "Jane", "id": "user-789" },
  "botDivId": "myChat",

  // ── Language ──
  "locale": "el",
  "supportedLocales": ["en", "el"],
  "showLocaleSelector": true,

  // ── Session & message history ──
  "sessionDuration": 30,
  "keepTranscript": true,
  "messageHistory": {
    "enabled": true,
    "sendGreetingMessage": false,
    "maxNumberOfMessages": 50,
    "maxNumberOfSessions": 3
  },

  // ── Greetings & notifications ──  (these arrays REPLACE)
  "entryPoint": "node-welcome",
  "greetingMessages": [ { "conversationNodeId": "node-welcome", "quick": [], "triggerWhenInactiveFor": 0 } ],
  "startUpNotifications": [                           // UI
    {
      "text": "We're online!",
      "level": "INFO",
      "id": "n1",
      "hasSound": true,
      "imageUrl": "https://…/promo.png",
      "imageLink": "https://example.com",
      "buttons": [ { "type": "HCN", "title": "Talk to us", "conversationNodeId": "node-start" } ]
    }
  ],
  "idleNotifications": [                              // UI
    {
      "text": "Still there?",
      "level": "INFO",
      "id": "n2",
      "hasSound": true,
      "imageUrl": "https://…/promo.png",
      "imageLink": "https://example.com",
      "buttons": [ { "type": "HCN", "title": "Talk to us", "conversationNodeId": "node-start" } ],
      "triggerWhenInactiveFor": 60,
      "triggerConversationNodeId": "node-idle"
    }
  ],
  "messageSoundNotifications": "livechat",           

  // ── Send box behavior ──
  "disableSendBoxOnStart": true,
  "startupNotificationsRequireDismissal": false,
  "disableSendBoxOnSuggestedActions": false,
  "disableSendBoxOnCards": true,
  "disableSendBoxAfterMessageDuration": 2000,
  "keepCardButtonsEnabledAfterClick": true,

  // ── File uploads ──
  "maxFileSizeForUpload": 8388608,
  "enableFileUploadOnDemand": true,                  

  // ── Speech / voice ──
  "allowSpeechToText": true,                         // UI
  "ttsVoiceName": "en-US-JennyNeural",
  "ttsLexiconUrl": "https://my-bucket.s3.amazonaws.com/lexicon.xml",
  "speechSubscriptionKey": "key-123",
  "speechRegion": "eastus",
  "sttReplacements": [
    { "match": " acme", "replacement": "ACME", "flags": "i", "wholeWord": true }
  ],

  // ── Widget type & links ──
  "widgetStyle": "EMBEDDED",                         // UI
  "linkTarget": "_self",
  "showErrorFallback": true,

  // ── Developer / integration hooks ──  (retrieve* are BLOCKED → set as window.HBF_* globals)
  "sendUserLeftEvent": true,
  "customFunctionsIntervalTime": 30,
  "invokeCustomFunctionsOnBeforeMessages": true
}

Every key in the block is documented below.

Key

Description

Default

Example

id

(BLOCKED) Unique webchat id (UUIDv4); platform-set.

""

"a1b2c3d4-…"

tokenURL

(BLOCKED) DirectLine token endpoint; platform-set.

""

"https://…/token"

azureSpeechTokenURL

Speech token endpoint URL; an empty string is ignored.

""

"https://…/speech"

azureSpeechSynthesisDeploymentId

Text-to-speech voice deployment id (advanced).

""

"deploy-123"

domain

DirectLine service address override (advanced).

not set

"https://…/v3/directline"

secret

DirectLine secret; also lets bot be set here.

not set

"abc123"

bot.id

(BLOCKED unless secret set) Bot internal id.

""

"bot-001"

bot.name

(BLOCKED unless secret set) Bot display name.

""

"Support Bot"

bot.role

(BLOCKED unless secret set) Bot role label.

"bot"

user.name

Visitor's display name.

"Webchat User"

"Jane"

user.id

Visitor id; usually set from the session.

""

"user-789"

botDivId

Id of the page element the widget mounts into.

"botDiv"

"myChat"

locale

Starting language code.

"en"

"el"

supportedLocales

Languages the visitor can pick from.

["en"]

["en", "el"]

showLocaleSelector

Show a language picker.

false

true

sessionDuration

Days a chat session stays valid.

365

30

keepTranscript

Keep transcript in memory while the page is open (needed for getTranscript()).

false

true

messageHistory.enabled

Reload previous messages when the visitor returns.

false

true

messageHistory.sendGreetingMessage

Re-send the greeting when history reloads.

false

true

messageHistory.maxNumberOfMessages

Max messages to reload; 0 disables reload.

100

50

messageHistory.maxNumberOfSessions

Past sessions to reload; 0 = all sessions.

1

3

entryPoint

Node used as the greeting/entry; usually set from the deployment.

not set

"node-welcome"

greetingMessages

Auto messages when the chat opens (replace-array).

not set

(rows below)

greetingMessages[].conversationNodeId

Bot flow node to trigger as the greeting.

not set

"node-welcome"

greetingMessages[].quick

Pre-built messages or quick-reply buttons.

not set

—

greetingMessages[].triggerWhenInactiveFor

Seconds of inactivity before sending.

required

0

startUpNotifications

(UI) Banners shown on load (replace-array).

not set

(rows below)

startUpNotifications[].text

Notification message (optional; image-only is allowed).

not set

"We're online!"

startUpNotifications[].level

Severity: ERROR, INFO, SUCCESS, WARN.

required

"INFO"

startUpNotifications[].id

Optional internal id.

not set

"n1"

startUpNotifications[].hasSound

Play a sound with the notification.

not set

true

startUpNotifications[].imageUrl

Image to show.

not set

"https://…/promo.png"

startUpNotifications[].imageLink

Page opened when the image is clicked.

not set

"https://example.com"

startUpNotifications[].buttons[].type

DISMISS (close) or HCN (trigger a bot flow).

required

"HCN"

startUpNotifications[].buttons[].title

Button label.

required

"Talk to us"

startUpNotifications[].buttons[].conversationNodeId

Flow node to trigger (for an HCN button).

required for HCN

"node-start"

idleNotifications

(UI) Banners shown after inactivity (replace-array).

not set

(rows below)

idleNotifications[].text

Notification message (required for idle).

required

"Still there?"

idleNotifications[].level

Severity: ERROR, INFO, SUCCESS, WARN.

required

"INFO"

idleNotifications[].id

Optional internal id.

not set

"n2"

idleNotifications[].hasSound

Play a sound with the notification.

not set

true

idleNotifications[].imageUrl

Image to show.

not set

"https://…/promo.png"

idleNotifications[].imageLink

Page opened when the image is clicked.

not set

"https://example.com"

idleNotifications[].buttons[].type

DISMISS (close) or HCN (trigger a bot flow).

required

"HCN"

idleNotifications[].buttons[].title

Button label.

required

"Talk to us"

idleNotifications[].buttons[].conversationNodeId

Flow node to trigger (for an HCN button).

required for HCN

"node-start"

idleNotifications[].triggerWhenInactiveFor

Seconds of inactivity before showing.

required

60

idleNotifications[].triggerConversationNodeId

Optional bot flow node to trigger.

not set

"node-idle"

messageSoundNotifications

Play sounds for all messages or only livechat (agent) messages.

not set

"livechat"

idleReminderMessages

(DEPRECATED) Use idleNotifications instead.

not set

—

disableSendBoxOnStart

Lock the input box when the chat opens.

false

true

startupNotificationsRequireDismissal

Lock input until a start-up notification is dismissed.

false

true

disableSendBoxOnSuggestedActions

Lock typing when buttons or cards are shown.

true

false

disableSendBoxOnCards

Lock typing only when cards are shown.

false

true

disableSendBoxAfterMessageDuration

Lock typing for N milliseconds after a message is sent.

not set

2000

keepCardButtonsEnabledAfterClick

Keep card buttons clickable after a click.

false

true

maxFileSizeForUpload

Largest uploadable file, in bytes (4194304 = 4 MB).

4194304

8388608

enableFileUploadOnDemand

Allow uploads only when the bot asks for a file.

false

true

fileTooLargeConversationNodeId

(DEPRECATED) Node when a file is too big; handle in the flow instead.

not set

"node-toobig"

allowSpeechToText

(UI) Enable the microphone (speech-to-text).

false

true

ttsVoiceName

Azure text-to-speech voice used to read messages aloud.

not set

"en-US-JennyNeural"

ttsLexiconUrl

URL of an Azure custom lexicon (PLS/XML) for text-to-speech pronunciation.

not set

"https://…/lexicon.xml"

speechSubscriptionKey

Azure Speech key (advanced).

not set

"key-123"

speechRegion

Azure Speech region (advanced).

not set

"eastus"

sttReplacements

Find/replace rules applied to dictated speech only.

[]

(rows below)

sttReplacements[].match

Text to find, written as a regular expression.

required

"acme"

sttReplacements[].replacement

Written form that replaces each match.

required

"ACME"

sttReplacements[].flags

Extra regex flags, e.g. "i" for case-insensitive.

not set

"i"

sttReplacements[].wholeWord

Match only as a standalone word.

true

false

widgetStyle

(UI) BUBBLE (floating button) or EMBEDDED (in-page). Also selects the widgetStyleSet shape.

"BUBBLE"

"EMBEDDED"

linkTarget

Where chat links open: _blank (new tab) or _self (same tab).

"_blank"

"_self"

showErrorFallback

Show a fallback message if the widget fails to load.

not set

true

sendUserLeftEvent

Notify the bot when the visitor leaves the page.

false

true

customFunctionsIntervalTime

Seconds between custom-function runs; 0 = run once.

0

30

invokeCustomFunctionsOnBeforeMessages

Run custom functions before messages are sent.

false

true

retrieveUserIdFromLogin

(BLOCKED) Read the visitor id from login; use window.HBF_retrieveUserId.

built-in

—

retrieveUserInfoFromLogin

(BLOCKED) Read visitor details from login; use window.HBF_retrieveUserInfo.

built-in

—

retrieveMetadata

(BLOCKED) Attach extra data to the chat; use window.HBF_retrieveMetadata.

built-in

—

Widget Style controls the chat frame: the launcher, window, header, and attention pop-ups. Every key lives under widgetStyleSet, and the paths in the tables below are shown relative to it.

The widget takes one of two shapes, set by the top-level widgetStyle:

Bubble: A floating launcher button that opens a chat window
Embedded: The chat placed directly in the page

Each mode has its own example and table below. A few keys, such as borderRadius, header, and hcnButtons, apply to both.

The Bubble widget is a floating launcher button and the chat window it opens. A Bubble widget block at a glance:

{
  "widgetStyle": "BUBBLE",
  "widgetStyleSet": {
    // Window & size
    "color": "#605dec",
    "height": "650px",
    "width": "376px",
    "borderRadius": "20px",

    // Launcher button (FAB)
    "fabIconOpen": "https://…/open.svg",
    "fabIconClose": "https://…/close.svg",
    "fabIconPadding": "25%",
    "fabButtonBorder": 5,
    "fabAnimation": { "variant": "bounce", "durationMs": 1400, "iterationCount": "infinite" },
    "fabHoverAnimation": "zoom",
    "fabOpenCloseIconAnimation": "rotate",
    "tooltip": "Need help?",

    // Header
    "header": {
      "text": "Chat with us",
      "subtitleText": "We reply in minutes",
      "showSubtitle": true,
      "backgroundColor": "#605dec",
      "textColor": "#FFFFFF",
      "fontFamily": "Arial",
      "logo": "https://…/logo.png",
      "headerStyle": "left",
      "headerBorderRadius": "10px",
      "headerHeight": "60px",
      "headerMargin": "0"
    },

    // Attention pop-ups
    "autoPopOut": { "enable": true, "delayInSeconds": 5, "extendTimeAfterView": true, "once": true },
    "userPromptBubble": { "enable": true, "delayInSeconds": 3, "message": "Hi! Need any help?" },
    "advancedChatPromptBubble": {
      "enable": true,
      "stepOneMessage": "Hello!",
      "stepOneButtonLabel": "Chat now",
      "stepTwoMessage": "Pick a channel:",
      "deployments": [ { "icon": "https://…/whatsapp.png", "url": "https://wa.me/…" } ]
    },

    // Quick-action buttons
    "hcnButtons": [
      { "conversationNodeId": "node-order-status", "title": "Track my order", "language": "en", "icon": "https://…/track.png" }
    ]
  }
}

Every key in the block is documented below.

Key

Description

Default

Example

color

Launcher button color.

"#605dec"

height

Height of the open chat window (CSS length). Overrides the Console width/height setting.

"650px"

width

Width of the open chat window (CSS length). Overrides the console width/height setting.

"376px"

borderRadius

Corner rounding of the chat window (CSS length).

"20px"

fabIconOpen

Icon shown when the chat is closed (URL).

not set

"https://…/open.svg"

fabIconClose

Icon shown when the chat is open (URL).

not set

"https://…/close.svg"

fabIconPadding

Space around the launcher icon; number = px, string = any CSS length.

"25%"

fabButtonBorder

Thickness of the button's outer ring; number = px.

5

0

fabAnimation.variant

Launcher animation: pulse, bounce, or none.

"pulse"

"bounce"

fabAnimation.durationMs

One animation cycle length, in ms.

1000 pulse / 1400 bounce

1400

fabAnimation.iterationCount

How many times it repeats; number or "infinite".

5

"infinite"

fabHoverAnimation

Hover effect: zoom or none.

not set

"zoom"

fabOpenCloseIconAnimation

Open/close icon switch effect: rotate or none.

not set

"rotate"

pulse

(DEPRECATED) Old launcher pulse; use fabAnimation instead.

not set

—

tooltip

Message shown over the launcher button.

not set

"Need help?"

header.text

Header title.

"Chat"

"Chat with us"

header.subtitleText

Smaller text under the title (supports links).

Helvia.ai credit

"We reply in minutes"

header.showSubtitle

Show or hide the subtitle.

true

false

header.backgroundColor

Header background color.

"#605dec"

header.textColor

Header text color.

"#F0F0F0"

"#FFFFFF"

header.fontFamily

Header font.

Calibri stack

"Arial"

header.logo

Logo image in the header (URL).

default Helvia avatar

"https://…/logo.png"

header.headerStyle

Header layout: center or left.

"center"

"left"

header.headerBorderRadius

Header corner rounding; number = px or CSS length.

not set

"10px"

header.headerHeight

Header height; number = px or CSS length.

not set

"60px"

header.headerMargin

Space around the header; number = px or CSS length.

not set

"0"

autoPopOut.enable

Open the chat automatically after a delay.

not set (off)

true

autoPopOut.delayInSeconds

Seconds to wait before opening.

not set

5

autoPopOut.extendTimeAfterView

Reset the timer after the visitor has seen it.

not set

true

autoPopOut.once

Only open automatically once per visitor.

not set

true

userPromptBubble.enable

Show a small invite bubble by the launcher.

not set (off)

true

userPromptBubble.delayInSeconds

Seconds before showing it.

not set

3

userPromptBubble.message

Text in the bubble.

not set

"Hi! Need any help?"

advancedChatPromptBubble.enable

Two-step invite bubble that can offer channels.

not set (off)

true

advancedChatPromptBubble.stepOneMessage

First message shown.

not set

"Hello!"

advancedChatPromptBubble.stepOneButtonLabel

Button to go to step two.

not set

"Chat now"

advancedChatPromptBubble.stepTwoMessage

Second message shown.

not set

"Pick a channel:"

advancedChatPromptBubble.deployments[].icon

Channel icon (URL).

not set

"https://…/whatsapp.png"

advancedChatPromptBubble.deployments[].url

Optional link for that channel.

not set

"https://wa.me/…"

hcnButtons[].conversationNodeId

Bot flow node the button triggers.

required

"node-order-status"

hcnButtons[].title

Button label.

required

"Track my order"

hcnButtons[].language

Optional language for the button.

not set

"en"

hcnButtons[].icon

Optional button icon (URL).

not set

"https://…/track.png"

The Embedded widget places the chat directly inside a container on your page, with no floating launcher button. An Embedded widget block at a glance:

{
  "widgetStyle": "EMBEDDED",
  "widgetStyleSet": {
    "borderRadius": "20px",
    "appendOnBodyAsFallback": true,
    "header": {
      "text": "Chat with us",
      "subtitleText": "We reply in minutes",
      "backgroundColor": "#605dec",
      "textColor": "#FFFFFF",
      "fontFamily": "Arial",
      "logo": "https://…/logo.png"
    },
    "footer": {
      "text": "Powered by helvia.ai",
      "fontFamily": "Arial"
    },
    "hcnButtons": [
      { "conversationNodeId": "node-menu", "title": "Menu", "language": "en", "icon": "https://…/i.png" }
    ]
  }
}

Every key in the block is documented below.

Key

Description

Default

Example

borderRadius

Corner rounding of the embedded chat (CSS length).

"20px"

"25px"

appendOnBodyAsFallback

If its container is missing, attach the chat to the page body instead.

false

true

header.text

Header title.¹

"Chat"

"Chat with us"

header.subtitleText

Smaller text under the title.

not set

"We reply in minutes"

header.backgroundColor

Header background color.¹

"#605dec"

header.textColor

Header text color.¹

"#F0F0F0"

"#FFFFFF"

header.fontFamily

Header font.¹

Calibri stack

"Arial"

header.logo

Logo image in the header (URL).¹

default Helvia avatar

"https://…/logo.png"

footer.text

Footer text (supports links).

Helvia.ai credit

"Powered by helvia.ai"

footer.fontFamily

Footer font.

not set

"Arial"

hcnButtons[].conversationNodeId

Bot flow node the button triggers.

required

"node-menu"

hcnButtons[].title

Button label.

required

"Menu"

hcnButtons[].language

Optional language for the button.

not set

"en"

hcnButtons[].icon

Optional button icon (URL).

not set

"https://…/i.png"

¹ The embedded header is off by default. When you provide a header, any fields you omit fall back to the default values.

Widget theme controls the look inside the chat: colors, fonts, message bubbles, avatars, buttons, and toasts. Every key lives under styleSetOptions, and the paths in the tables below are shown relative to it. The theme defaults are the same for Bubble and Embedded widgets, so one set of values applies regardless of widgetStyle.

The theme keys are split into two subsections:

Helvia.ai theme keys: extra styling keys Helvia.ai adds on top of Bot Framework Web Chat.
Microsoft theme keys: the standard options built into Bot Framework Web Chat v4.18.0.

The Helvia.ai defined keys are a small set. The Microsoft set is exhaustive, and most of its keys you will never set.

Helvia.ai Theme Settings

The Helvia.ai theme keys are extra styling controls Helvia.ai adds on top of Bot Framework Web Chat. They fine-tune specific elements such as action buttons, the send box, CSAT surveys, and carousel cards.

A Helvia.ai theme block at a glance:

{
  "styleSetOptions": {
    // Links & fonts
    "hyperlinkColor": "#2196f3",
    "primaryFontSize": 16,

    // Action buttons & reactions
    "actionButtonBackground": "#CED6F7",
    "actionButtonTextColor": "#263398",
    "actionButtonBorderRadius": "6px",
    "messageReactionButtonColor": "#605dec",

    // Send box (emoji, home & custom action buttons, send icon)
    "hideEmojiPickerButton": true,
    "sendBoxHomeActionButtonEnabled": true,
    "sendBoxHomeActionButtonIconUrl": "https://…/home.svg",
    "sendBoxCustomActionButtonEnabled": true,
    "sendBoxCustomActionButtonTriggerNodeId": "node-menu",
    "sendBoxCustomActionButtonIconUrl": "https://…/star.svg",
    "sendBoxSendIcon": "<svg …></svg>",

    // CSAT survey
    "csatMainColor": "#605dec",
    "csatFontColor": "#333",
    "csatFontFamily": "Arial",
    "csatFontSize": 14,
    "csatButtonFontColor": "#ffffff",
    "hideCsatExplanations": false,

    // Carousel cards
    "carouselCardWidth": 275,
    "carouselCardSpacing": 45,
    "carouselTextColor": "#333",
    "carouselCardBackgroundColor": "White",
    "carouselArrowBackgroundColor": "#605dec",
    "carouselArrowColor": "White",
    "carouselArrowHoverBackgroundColor": "#403db0",
    "carouselArrowHoverColor": "White",

    // Live chat
    "hideEndLiveChatButton": false,
    "terminateLivechatConfirmation": "End this chat?",

    // Speech microphone & listening overlay
    "sendBoxMicrophoneButtonColorOnListening": "#605dec",
    "listeningOverlayBackgroundColor": "#000",
    "listeningOverlayBorderRadius": "10px",
    "listeningOverlayMargin": "8px"
  }
}

Every key in the block is documented below.

Key

Description

Default

Example

hyperlinkColor

Color of links inside bot messages and notifications.

"#2196f3"

primaryFontSize

Base font size across the widget UI (number = px).

16

actionButtonBackground

Background of action buttons (suggested actions, adaptive cards, end-live-chat, confirmation).

"#CED6F7"

actionButtonTextColor

Text/label color of those action buttons.

"#263398"

actionButtonBorderRadius

Corner rounding of action buttons.

"6px"

messageReactionButtonColor

Color of the thumbs-up/down reaction icons on bot messages.

"#605dec"

hideEmojiPickerButton

Hide the emoji-picker button in the send box.

false

true

csatMainColor

Primary accent of the CSAT survey popup (backgrounds, borders, selected stars, close icon).

"#605dec"

csatFontColor

Text color inside the CSAT popup.

not set (uses csatMainColor)

"#333"

csatFontFamily

Font family of the CSAT popup.

Calibri stack

"Arial"

csatFontSize

Base font size of the CSAT popup text.

not set (uses primaryFontSize)

14

csatButtonFontColor

Text color of the CSAT submit button.

"#ffffff"

hideCsatExplanations

Hide the helper text under CSAT/rating options.

true

false

sendBoxHomeActionButtonEnabled

Add a "home" button to the send box that posts back to the bot's entry point.

false

true

sendBoxHomeActionButtonIconUrl

Custom icon (URL) for the home button; use a square (1:1) image.

not set (built-in icon)

"https://…/home.svg"

sendBoxCustomActionButtonEnabled

Add a second, custom action button to the send box.

false

true

sendBoxCustomActionButtonTriggerNodeId

Flow node the custom action button posts back to.

not set

"node-menu"

sendBoxCustomActionButtonIconUrl

Custom icon (URL) for the custom action button; use a square (1:1) image.

not set (built-in icon)

"https://…/star.svg"

sendBoxSendIcon

Custom SVG markup for the send button (falls back to the default arrow if invalid).

built-in arrow

"<svg …></svg>"

carouselCardWidth

Width of each carousel card (number = px). Ignored when the bubble widget is ≤410px wide.

275

carouselCardSpacing

Gap between carousel cards (number = px). Ignored when the bubble widget is ≤410px wide.

45

carouselTextColor

Text color inside carousel cards.

"inherit"

"#333"

carouselCardBackgroundColor

Carousel card background/border color.

not set (uses bubbleBackground)

"White"

carouselArrowBackgroundColor

Background of the carousel navigation arrows.

not set (uses actionButtonTextColor)

"#605dec"

carouselArrowColor

Color of the carousel arrow icons.

not set (uses actionButtonBackground)

"White"

carouselArrowHoverBackgroundColor

Arrow background on hover.

not set (uses actionButtonBackground)

"#403db0"

carouselArrowHoverColor

Arrow icon color on hover.

not set (uses actionButtonTextColor)

"White"

hideEndLiveChatButton

When explicitly false, shows an "End Live Chat" button on bot messages during a live chat (default true hides it).

true

false

terminateLivechatConfirmation

Custom title text in the "end live chat" confirmation popover.

not set (localized default)

"End this chat?"

sendBoxMicrophoneButtonColorOnListening

Microphone button color while actively listening.

not set (defaults to #ff3333)

"#605dec"

listeningOverlayBackgroundColor

Background of the speech "listening" overlay backdrop.

not set

"#000"

listeningOverlayBorderRadius

Corner rounding of the listening overlay.

not set

"10px"

listeningOverlayMargin

Outer margin of the listening overlay.

not set

"8px"

Microsoft Theme Settings

These are the standard styling options built into Bot Framework Web Chat v4.18.0. There are many settings (more than 200), so they are grouped by area. Each group, such as General & layout or Fonts & markdown, has its own example and table. Set only the keys you need from any group.

For the full list of options from the Microsoft source, see StyleOptions reference.

General & Layout

{
  "styleSetOptions": {
    "accent": "#605dec",
    "backgroundColor": "White",
    "subtle": "#909090",
    "paddingRegular": 12,
    "paddingWide": 24,
    "transitionDuration": "0.2s",
    "rootHeight": "100%",
    "rootWidth": "100%",
    "rootZIndex": 0,
    "maxMessageLength": 2000,
    "messageActivityWordBreak": "break-word"
  }
}

Key

Description

Default

Example

accent

Main accent color used across the chat.

"#605dec"

backgroundColor

Transcript (chat) background color.

"White"

subtle

Color for secondary/faint text and icons.

"#909090"

paddingRegular

Standard padding inside components (px).

12

paddingWide

Wider padding, used for suggested-action buttons (px).

24

transitionDuration

Duration of visual transitions.

"0s"

"0.2s"

rootHeight

Height of the chat root container.

"100%"

rootWidth

Width of the chat root container.

"100%"

rootZIndex

Stacking order of the root container.

0

maxMessageLength

Most characters a visitor can type in one message.

2000

messageActivityWordBreak

Word-break for message text: normal, break-all, break-word, keep-all.

"break-word"

Fonts & Markdown

{
  "styleSetOptions": {
    "fontSizeSmall": "80%",
    "monospaceFont": "Consolas, monospace",
    "primaryFont": "Arial, sans-serif",
    "markdownRespectCRLF": true,
    "markdownRenderHTML": true,
    "markdownExternalLinkIconImage": "url(…)"
  }
}

Key

Description

Default

Example

fontSizeSmall

Size for secondary text (e.g. send status).

"80%"

"90%"

monospaceFont

Font for code blocks / error boxes.

Consolas stack

"Consolas"

primaryFont

Main font for the chat.

Calibri stack

"Arial"

markdownRespectCRLF

Preserve line breaks in formatted text.

true

markdownRenderHTML

Allow HTML inside Markdown messages.

true

markdownExternalLinkIconImage

Icon shown next to external links.

built-in icon

"url(…)"

Message Bubbles

{
  "styleSetOptions": {
    "bubbleBackground": "#ECEFF1",
    "bubbleBorderColor": "#ECEFF1",
    "bubbleBorderRadius": "12px",
    "bubbleBorderStyle": "solid",
    "bubbleBorderWidth": 1,
    "bubbleTextColor": "#333",
    "bubbleFromUserBackground": "#E8EAFD",
    "bubbleFromUserBorderColor": "#E8EAFD",
    "bubbleFromUserBorderRadius": "12px",
    "bubbleFromUserBorderStyle": "solid",
    "bubbleFromUserBorderWidth": 1,
    "bubbleFromUserTextColor": "#0D1C8C",
    "bubbleNubOffset": 0,
    "bubbleNubSize": 10,
    "bubbleFromUserNubOffset": 0,
    "bubbleFromUserNubSize": 10,
    "bubbleImageHeight": 240,
    "bubbleMaxWidth": 480,
    "bubbleMinWidth": 250,
    "bubbleMinHeight": 40
  }
}

Key

Description

Default

Example

bubbleBackground

Bot bubble background.

"#ECEFF1"

bubbleBorderColor

Bot bubble border color.

"#ECEFF1"

bubbleBorderRadius

Bot bubble corner radius. Declared number, but accepts a CSS length string (type-override).

"25px 25px 25px 0"

"30px 25px 25px 0"

bubbleBorderStyle

Bot bubble border style.

"solid"

bubbleBorderWidth

Bot bubble border width.

0

1

bubbleTextColor

Bot bubble text color.

"#333"

bubbleFromUserBackground

Visitor bubble background.

"#E8EAFD"

bubbleFromUserBorderColor

Visitor bubble border color.

"#E8EAFD"

bubbleFromUserBorderRadius

Visitor bubble corner radius. Declared number, but accepts a CSS length string (type-override).

"25px 25px 0 25px"

"30px 25px 0 25px"

bubbleFromUserBorderStyle

Visitor bubble border style.

"solid"

bubbleFromUserBorderWidth

Visitor bubble border width.

0

1

bubbleFromUserTextColor

Visitor bubble text color.

"#0D1C8C"

bubbleFromUserNubOffset

Visitor bubble nub vertical offset (top/bottom/number).

"bottom"

0

bubbleFromUserNubSize

Visitor bubble nub size (0 = no nub).

0

10

bubbleNubOffset

Bot bubble nub vertical offset (top/bottom/number).

"bottom"

0

bubbleNubSize

Bot bubble nub size (0 = no nub).

0

10

bubbleImageHeight

Max height of images shown in bubbles (px).

240

bubbleMaxWidth

Maximum bubble width (px).

480

bubbleMinWidth

Minimum bubble width (px).

250

bubbleMinHeight

Minimum bubble height (px).

40

Avatars

{
  "styleSetOptions": {
    "avatarSize": 32,
    "avatarBorderRadius": "50%",
    "showAvatarInGroup": "sender",
    "botAvatarImage": "https://…/bot.png",
    "botAvatarBackgroundColor": "White",
    "botAvatarInitials": "SB",
    "userAvatarImage": "https://…/user.png",
    "userAvatarBackgroundColor": "White",
    "userAvatarInitials": "JD"
  }
}

Key

Description

Default

Example

avatarSize

Height/width of avatars (px).

32

avatarBorderRadius

Avatar corner rounding (50% = circle).

"50%"

showAvatarInGroup

Which messages show an avatar: true, "sender", or "status".

true

"sender"

botAvatarImage

Bot avatar image (URL).

built-in bot avatar

"https://…/bot.png"

botAvatarBackgroundColor

Bot avatar background.

"White"

botAvatarInitials

Letters shown when no bot image.

""

"SB"

userAvatarImage

Visitor avatar image (URL).

built-in user avatar

"https://…/user.png"

userAvatarBackgroundColor

Visitor avatar background.

"White"

userAvatarInitials

Letters shown when no visitor image.

""

"JD"

Send Box

{
  "styleSetOptions": {
    "hideSendBox": false,
    "hideUploadButton": false,
    "hideTelephoneKeypadButton": false,
    "sendBoxBackground": "White",
    "sendBoxTextColor": "#333",
    "sendBoxHeight": 52,
    "sendBoxMaxHeight": 200,
    "sendBoxTextWrap": true,
    "sendBoxPlaceholderColor": "#999",
    "sendBoxDisabledTextColor": "#CCC",
    "sendBoxBorderTop": "solid 1px #E6E6E6",
    "sendBoxBorderBottom": "",
    "sendBoxBorderLeft": "",
    "sendBoxBorderRight": "",
    "sendBoxButtonColor": "#605dec",
    "sendBoxButtonColorOnHover": "#333",
    "sendBoxButtonColorOnFocus": "#333",
    "sendBoxButtonColorOnActive": "#333",
    "sendBoxButtonColorOnDisabled": "#A19F9D",
    "sendBoxButtonShadeColor": "transparent",
    "sendBoxButtonShadeColorOnHover": "#F3F2F1",
    "sendBoxButtonShadeColorOnFocus": "transparent",
    "sendBoxButtonShadeColorOnActive": "#EDEBE9",
    "sendBoxButtonShadeColorOnDisabled": "#F3F2F1",
    "sendBoxButtonShadeBorderRadius": 2,
    "sendBoxButtonShadeInset": 2,
    "sendBoxButtonAlignment": "stretch",
    "microphoneButtonColorOnDictate": "#F33",
    "showSpokenText": true,
    "sendAttachmentOn": "attach",
    "uploadAccept": "image/*",
    "uploadMultiple": true
  }
}

Key

Description

Default

Example

hideSendBox

Hide the typing box entirely.

false

true

hideUploadButton

Hide the file-upload button.

true

false

hideTelephoneKeypadButton

Hide the telephone-keypad button.

true

false

sendBoxBackground

Send box background color.

"White"

sendBoxTextColor

Text color while typing.

"#333"

sendBoxHeight

Send box height (px).

52

sendBoxMaxHeight

Send box maximum height (px).

200

sendBoxTextWrap

Allow the input text to wrap onto new lines.

false

true

sendBoxPlaceholderColor

Color of the placeholder hint.

not set (uses subtle)

"#999"

sendBoxDisabledTextColor

Text color when typing is locked.

not set (uses subtle)

"#CCC"

sendBoxBorderTop

Send box top border.

"solid 1px #E6E6E6"

sendBoxBorderBottom

Send box bottom border.

""

"solid 1px #E6E6E6"

sendBoxBorderLeft

Send box left border.

""

sendBoxBorderRight

Send box right border.

""

sendBoxButtonColor

Send box button icon color.

not set (uses subtle)

"#605dec"

sendBoxButtonColorOnHover

Button icon color on hover.

"#333"

sendBoxButtonColorOnFocus

Button icon color on focus.

"#333"

sendBoxButtonColorOnActive

Button icon color while active.

not set

"#333"

sendBoxButtonColorOnDisabled

Button icon color when disabled.

"#CCC"

"#A19F9D"

sendBoxButtonShadeColor

Background shade behind a send box button.

"transparent"

sendBoxButtonShadeColorOnHover

Shade on hover.

"transparent"

"#F3F2F1"

sendBoxButtonShadeColorOnFocus

Shade on focus.

"transparent"

sendBoxButtonShadeColorOnActive

Shade while active.

"transparent"

"#EDEBE9"

sendBoxButtonShadeColorOnDisabled

Shade when disabled.

"transparent"

"#F3F2F1"

sendBoxButtonShadeBorderRadius

Corner rounding of the button shade.

2

sendBoxButtonShadeInset

Inset of the button shade.

2

sendBoxButtonAlignment

Vertical alignment of send box buttons: stretch, top, bottom.

"stretch"

microphoneButtonColorOnDictate

Microphone color while recording.

"#F33"

showSpokenText

Visually show spoken text.

true

sendAttachmentOn

When files are sent: attach (immediately) or send.

"attach"

uploadAccept

Which file types the upload button accepts.

not set

"image/*"

uploadMultiple

Allow selecting several files at once.

true

Suggested Action Buttons

{
  "styleSetOptions": {
    "suggestedActionLayout": "stacked",
    "suggestedActionBackgroundColor": "White",
    "suggestedActionTextColor": "#605dec",
    "suggestedActionBorderColor": "#605dec",
    "suggestedActionBorderStyle": "solid",
    "suggestedActionBorderWidth": 2,
    "suggestedActionBorderRadius": "6px",
    "suggestedActionHeight": 40,
    "suggestedActionImageHeight": 20,
    "suggestedActionBackgroundColorOnHover": "White",
    "suggestedActionBackgroundColorOnFocus": "White",
    "suggestedActionBackgroundColorOnActive": "White",
    "suggestedActionBackgroundColorOnDisabled": "#EEE",
    "suggestedActionTextColorOnHover": "#333",
    "suggestedActionTextColorOnFocus": "#333",
    "suggestedActionTextColorOnActive": "#333",
    "suggestedActionTextColorOnDisabled": "#999",
    "suggestedActionBorderColorOnHover": "#605dec",
    "suggestedActionBorderColorOnFocus": "#605dec",
    "suggestedActionBorderColorOnActive": "#605dec",
    "suggestedActionBorderStyleOnHover": "solid",
    "suggestedActionBorderStyleOnFocus": "solid",
    "suggestedActionBorderStyleOnActive": "solid",
    "suggestedActionBorderWidthOnHover": 2,
    "suggestedActionBorderWidthOnFocus": 2,
    "suggestedActionBorderWidthOnActive": 2,
    "suggestedActionBorderColorOnDisabled": "#E6E6E6",
    "suggestedActionBorderStyleOnDisabled": "solid",
    "suggestedActionBorderWidthOnDisabled": 2,
    "suggestedActionsCarouselFlipperBoxWidth": 40,
    "suggestedActionsCarouselFlipperSize": 20,
    "suggestedActionsCarouselFlipperCursor": "pointer",
    "suggestedActionsFlowMaxHeight": 240,
    "suggestedActionsStackedHeight": 240,
    "suggestedActionsStackedOverflow": "auto",
    "suggestedActionsStackedLayoutButtonMaxHeight": "100%",
    "suggestedActionsStackedLayoutButtonTextWrap": true
  }
}

Key

Description

Default

Example

suggestedActionLayout

Layout: carousel, flow, or stacked.

"carousel"

"stacked"

suggestedActionBackgroundColor

Button background.

"White"

suggestedActionTextColor

Button text color.

not set (uses accent)

"#605dec"

suggestedActionBorderColor

Button border color.

not set (uses accent)

"#605dec"

suggestedActionBorderStyle

Button border style.

"solid"

suggestedActionBorderWidth

Button border width.

2

suggestedActionBorderRadius

Button corner rounding.

"6px"

suggestedActionHeight

Button height (px).

40

suggestedActionImageHeight

Image height inside buttons (px).

20

suggestedActionBackgroundColorOnHover

Background on hover.

"White"

suggestedActionBackgroundColorOnFocus

Background on focus.

"White"

suggestedActionBackgroundColorOnActive

Background while active.

"White"

suggestedActionBackgroundColorOnDisabled

Background when disabled.

not set

"#EEE"

suggestedActionTextColorOnHover / OnFocus / OnActive

Text color per state.

not set

"#333"

suggestedActionTextColorOnDisabled

Text color when disabled.

not set (uses subtle)

"#999"

suggestedActionBorderColorOnDisabled

Border color when disabled.

"#E6E6E6"

suggestedActionBorderStyleOnDisabled

Border style when disabled.

"solid"

suggestedActionBorderWidthOnDisabled

Border width when disabled.

2

suggestedActionBorderColorOnHover / OnFocus / OnActive

Border color per state.

not set

"#605dec"

suggestedActionBorderStyleOnHover / OnFocus / OnActive

Border style per state.

not set

"solid"

suggestedActionBorderWidthOnHover / OnFocus / OnActive

Border width per state.

not set

2

suggestedActionsCarouselFlipperBoxWidth

Carousel scroll-arrow bounding box (px).

40

suggestedActionsCarouselFlipperSize

Carousel scroll-arrow visible size (px).

20

suggestedActionsCarouselFlipperCursor

Cursor over the carousel arrows.

not set

"pointer"

suggestedActionsFlowMaxHeight

Max height of the button area in flow layout. Declared undefined, but accepts a number (type-override).

240

suggestedActionsStackedHeight

Max height of the button area in stacked layout.

240

suggestedActionsStackedOverflow

Stacked overflow: auto, hidden, scroll, visible.

not set

"auto"

suggestedActionsStackedLayoutButtonMaxHeight

Max height of a single stacked button.

not set

"100%"

suggestedActionsStackedLayoutButtonTextWrap

Allow long button text to wrap (stacked only).

false

true

suggestedActionBackground

(DEPRECATED) Use suggestedActionBackgroundColor.

not set

—

suggestedActionActiveBackground

(DEPRECATED) Use suggestedActionBackgroundColorOnActive.

not set

—

suggestedActionFocusBackground

(DEPRECATED) Use suggestedActionBackgroundColorOnFocus.

not set

—

suggestedActionHoverBackground

(DEPRECATED) Use suggestedActionBackgroundColorOnHover.

not set

—

suggestedActionDisabledBackground

(DEPRECATED) Use suggestedActionBackgroundColorOnDisabled.

not set

—

suggestedActionDisabledBorderColor

(DEPRECATED) Use suggestedActionBorderColorOnDisabled.

not set

—

suggestedActionDisabledBorderStyle

(DEPRECATED) Use suggestedActionBorderStyleOnDisabled.

not set

—

suggestedActionDisabledBorderWidth

(DEPRECATED) Use suggestedActionBorderWidthOnDisabled.

not set

—

suggestedActionDisabledTextColor

(DEPRECATED) Use suggestedActionTextColorOnDisabled.

not set

—

Timestamps

{
  "styleSetOptions": {
    "groupTimestamp": true,
    "timestampFormat": "relative",
    "timestampColor": "#999",
    "sendTimeout": 20000,
    "sendTimeoutForAttachments": 120000
  }
}

Key

Description

Default

Example

groupTimestamp

Group messages under one timestamp: true/false/number (ms window).

true

300000

timestampFormat

Time display: relative or absolute.

"relative"

timestampColor

Timestamp text color.

not set (uses subtle)

"#999"

sendTimeout

Time (ms) before a message is marked failed.

20000

sendTimeoutForAttachments

Same, for file attachments (ms).

120000

Toasts & Notifications

{
  "styleSetOptions": {
    "hideToaster": false,
    "notificationDebounceTimeout": 400,
    "notificationText": "#5E5E5E",
    "toasterHeight": 32,
    "toasterMaxHeight": 160,
    "toasterSingularMaxHeight": 50,
    "toastFontSize": "87.5%",
    "toastIconWidth": 36,
    "toastTextPadding": 6,
    "toastSeparatorColor": "#E8EAEC",
    "toastInfoBackgroundColor": "#605dec",
    "toastInfoColor": "white",
    "toastSuccessBackgroundColor": "#DFF6DD",
    "toastSuccessColor": "#107C10",
    "toastWarnBackgroundColor": "#FFF4CE",
    "toastWarnColor": "#3B3A39",
    "toastErrorBackgroundColor": "#FDE7E9",
    "toastErrorColor": "#A80000"
  }
}

Key

Description

Default

Example

hideToaster

Hide all toast banners.

true

false

notificationDebounceTimeout

Delay (ms) to avoid flickering notifications.

400

notificationText

Color of small notification text.

"#5E5E5E"

toasterHeight

Toaster height (px).

32

toasterMaxHeight

Toaster max height (px).

160

toasterSingularMaxHeight

Single-toast max height (px).

50

toastFontSize

Toast text size.

"87.5%"

toastIconWidth

Toast icon width (px).

36

toastTextPadding

Toast text padding (px).

6

toastSeparatorColor

Toast separator color.

"#E8EAEC"

toastInfoBackgroundColor / toastInfoColor

Info toast background / text.

"#605dec" / "white"

toastSuccessBackgroundColor / toastSuccessColor

Success toast background / text.

"#DFF6DD" / "#107C10"

—

toastWarnBackgroundColor / toastWarnColor

Warning toast background / text.

"#FFF4CE" / "#3B3A39"

—

toastErrorBackgroundColor / toastErrorColor

Error toast background / text.

"#FDE7E9" / "#A80000"

—

Connectivity

{
  "styleSetOptions": {
    "slowConnectivity": "#EAA300",
    "failedConnectivity": "#C50F1F",
    "slowConnectionAfter": 15000,
    "connectivityTextSize": "75%",
    "connectivityIconPadding": 14.4,
    "connectivityMarginLeftRight": 16.8,
    "connectivityMarginTopBottom": 9.6
  }
}

Key

Description

Default

Example

slowConnectivity

Color for the "slow connection" status.

"#EAA300"

failedConnectivity

Color for the "connection failed" status.

"#C50F1F"

slowConnectionAfter

Wait (ms) before showing "slow".

15000

connectivityTextSize

Status text size.

"75%"

connectivityIconPadding

Padding around the status icon (px).

14.4

connectivityMarginLeftRight

Left/right margin of the status (px).

16.8

connectivityMarginTopBottom

Top/bottom margin of the status (px).

9.6

Scroll-To-End Button

{
  "styleSetOptions": {
    "scrollToEndButtonBehavior": "unread",
    "scrollToEndButtonFontSize": 16,
    "autoScrollSnapOnActivity": true,
    "autoScrollSnapOnActivityOffset": 0,
    "autoScrollSnapOnPage": true,
    "autoScrollSnapOnPageOffset": 0
  }
}

Key

Description

Default

Example

scrollToEndButtonBehavior

When it shows: unread, any, or false (never).

"unread"

scrollToEndButtonFontSize

Button text size.

16

autoScrollSnapOnActivity

Pause auto-scroll after N activities (true/false/number).

false

true

autoScrollSnapOnActivityOffset

Over/underscroll (px) after activity snap.

0

autoScrollSnapOnPage

Pause auto-scroll after page fill (true/false/fraction).

false

true

autoScrollSnapOnPageOffset

Over/underscroll (px) after page snap.

0

newMessagesButtonFontSize

(DEPRECATED) Renamed to scrollToEndButtonFontSize.

not set

—

Typing & Loading Animations

{
  "styleSetOptions": {
    "typingAnimationDuration": 5000,
    "typingAnimationHeight": 35,
    "typingAnimationWidth": 53,
    "typingAnimationBackgroundImage": "url(…)",
    "spinnerAnimationHeight": 16,
    "spinnerAnimationWidth": 16,
    "spinnerAnimationPadding": 12,
    "spinnerAnimationBackgroundImage": "url(…)"
  }
}

Key

Description

Default

Example

typingAnimationDuration

How long the "typing…" animation shows (ms).

5000

typingAnimationHeight

Typing animation height (px).

35

typingAnimationWidth

Typing animation width (px).

53

typingAnimationBackgroundImage

Custom image for the typing animation.

built-in animation

"url(…)"

spinnerAnimationHeight

Loading spinner height (px).

16

spinnerAnimationWidth

Loading spinner width (px).

16

spinnerAnimationPadding

Loading spinner padding (px).

12

spinnerAnimationBackgroundImage

Custom image for the loading spinner.

not set

"url(…)"

Uploads & Video

{
  "styleSetOptions": {
    "enableUploadThumbnail": true,
    "uploadThumbnailWidth": 720,
    "uploadThumbnailHeight": 360,
    "uploadThumbnailQuality": 0.6,
    "uploadThumbnailContentType": "image/jpeg",
    "videoHeight": 270
  }
}

Key

Description

Default

Example

enableUploadThumbnail

Create a small preview for uploaded images.

true

uploadThumbnailWidth

Preview width (px).

720

uploadThumbnailHeight

Preview height (px).

360

uploadThumbnailQuality

Preview image quality (0–1).

0.6

uploadThumbnailContentType

Preview image format.

"image/jpeg"

videoHeight

Height of videos shown in chat (px).

270

Transcript & Overlay Buttons

{
  "styleSetOptions": {
    "transcriptOverlayButtonBackground": "rgba(0,0,0,.6)",
    "transcriptOverlayButtonBackgroundOnHover": "rgba(0,0,0,.8)",
    "transcriptOverlayButtonBackgroundOnFocus": "rgba(0,0,0,.8)",
    "transcriptOverlayButtonBackgroundOnDisabled": "rgba(0,0,0,.6)",
    "transcriptOverlayButtonColor": "White",
    "transcriptOverlayButtonColorOnDisabled": "White",
    "transcriptOverlayButtonColorOnHover": "White",
    "transcriptOverlayButtonColorOnFocus": "White",
    "transcriptTerminatorBackgroundColor": "#595959",
    "transcriptTerminatorColor": "White",
    "transcriptTerminatorFontSize": 12,
    "transcriptTerminatorBorderRadius": 5
  }
}

Key

Description

Default

Example

transcriptOverlayButtonBackground

Background of overlay buttons (e.g. save image).

"rgba(0, 0, 0, .6)"

"rgba(0,0,0,.6)"

transcriptOverlayButtonBackgroundOnHover

Overlay button background on hover.

"rgba(0, 0, 0, .8)"

—

transcriptOverlayButtonBackgroundOnFocus

Overlay button background on focus.

"rgba(0, 0, 0, .8)"

—

transcriptOverlayButtonBackgroundOnDisabled

Overlay button background when disabled.

"rgba(0, 0, 0, .6)"

—

transcriptOverlayButtonColor

Overlay button icon/text color.

"White"

transcriptOverlayButtonColorOnDisabled

Overlay button color when disabled.

"White"

—

transcriptOverlayButtonColorOnHover / OnFocus

Overlay button color on hover/focus.

not set (uses base color)

—

transcriptTerminatorBackgroundColor

Background of the "live chat ended" divider.

"#595959"

transcriptTerminatorColor

Text color of that divider.

"White"

transcriptTerminatorFontSize

Text size of that divider (px).

12

transcriptTerminatorBorderRadius

Corner rounding of that divider.

5

Emoji

{
  "styleSetOptions": {
    "emojiSet": true
  }
}

Key

Description

Default

Example

emojiSet

Enable the built-in emoji set (true) or supply a custom emoticon→emoji map.

true

Accessibility & Keyboard Focus

Rarely changed. They style focus outlines during keyboard navigation.

{
  "styleSetOptions": {
    "internalLiveRegionFadeAfter": 1000,
    "sendBoxButtonKeyboardFocusIndicatorBorderColor": "#605E5C",
    "sendBoxButtonKeyboardFocusIndicatorBorderStyle": "solid",
    "sendBoxButtonKeyboardFocusIndicatorBorderWidth": 1,
    "sendBoxButtonKeyboardFocusIndicatorBorderRadius": 0,
    "sendBoxButtonKeyboardFocusIndicatorInset": 4,
    "suggestedActionKeyboardFocusIndicatorBorderColor": "#605E5C",
    "suggestedActionKeyboardFocusIndicatorBorderStyle": "dashed",
    "suggestedActionKeyboardFocusIndicatorBorderWidth": 1,
    "suggestedActionKeyboardFocusIndicatorBorderRadius": 0,
    "suggestedActionKeyboardFocusIndicatorInset": 2,
    "suggestedActionsVisualKeyboardIndicatorColor": "Black",
    "suggestedActionsVisualKeyboardIndicatorStyle": "solid",
    "suggestedActionsVisualKeyboardIndicatorWidth": 2,
    "transcriptVisualKeyboardIndicatorColor": "Black",
    "transcriptVisualKeyboardIndicatorStyle": "solid",
    "transcriptVisualKeyboardIndicatorWidth": 0,
    "transcriptActivityVisualKeyboardIndicatorColor": "#909090",
    "transcriptActivityVisualKeyboardIndicatorStyle": "dashed",
    "transcriptActivityVisualKeyboardIndicatorWidth": 0
  }
}

Key

Description

Default

Example

internalLiveRegionFadeAfter

How long (ms) screen-reader announcements stay before fading.

1000

sendBoxButtonKeyboardFocusIndicatorBorderColor

Focus outline color on send box buttons.

"#605E5C"

sendBoxButtonKeyboardFocusIndicatorBorderStyle

Focus outline style on send box buttons.

"solid"

sendBoxButtonKeyboardFocusIndicatorBorderWidth

Focus outline width on send box buttons.

1

sendBoxButtonKeyboardFocusIndicatorBorderRadius

Focus outline radius on send box buttons.

0

sendBoxButtonKeyboardFocusIndicatorInset

Focus outline inset on send box buttons.

4

suggestedActionKeyboardFocusIndicatorBorderColor

Focus outline color on suggested actions.

"#605E5C"

suggestedActionKeyboardFocusIndicatorBorderStyle

Focus outline style on suggested actions.

"dashed"

suggestedActionKeyboardFocusIndicatorBorderWidth

Focus outline width on suggested actions.

1

suggestedActionKeyboardFocusIndicatorBorderRadius

Focus outline radius on suggested actions.

0

suggestedActionKeyboardFocusIndicatorInset

Focus outline inset on suggested actions.

2

suggestedActionsVisualKeyboardIndicatorColor

Outline color on a focused suggested action.

"Black"

suggestedActionsVisualKeyboardIndicatorStyle

Outline style on a focused suggested action.

"solid"

suggestedActionsVisualKeyboardIndicatorWidth

Outline width on a focused suggested action.

2

transcriptVisualKeyboardIndicatorColor

Outline color around the focused transcript.

"Black"

transcriptVisualKeyboardIndicatorStyle

Outline style around the focused transcript.

"solid"

transcriptVisualKeyboardIndicatorWidth

Outline width around the focused transcript.

0

transcriptActivityVisualKeyboardIndicatorColor

Outline color around a focused message.

"#909090"

transcriptActivityVisualKeyboardIndicatorStyle

Outline style around a focused message.

"dashed"

transcriptActivityVisualKeyboardIndicatorWidth

Outline width around a focused message.

0

You can now configure any part of the Webchat widget through Custom Settings, from connection and behavior to its full visual theme.

PreviousLayout Settings

NextThird-Party Channels

Last updated 2 hours ago

Custom Settings

What Are Custom Settings

Applying Custom Settings

How This Page Is Organized

Core Settings

Widget Style

Widget Theme

Core Settings

Widget Style

Bubble Widget

Embedded Widget

Widget Theme

Helvia.ai Theme Settings

Microsoft Theme Settings

General & Layout

Fonts & Markdown

Message Bubbles

Avatars

Send Box

Suggested Action Buttons

Timestamps

Toasts & Notifications

Connectivity

Scroll-To-End Button

Typing & Loading Animations

Uploads & Video

Transcript & Overlay Buttons

Emoji

Accessibility & Keyboard Focus