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

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.
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:
Every key in the block is documented below.
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"
"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
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.
Bubble Widget
The Bubble widget is a floating launcher button and the chat window it opens. A Bubble widget block at a glance:
Every key in the block is documented below.
color
Launcher button color.
"#605dec"
"#605dec"
height
Height of the open chat window (CSS length). Overrides the Console width/height setting.
"650px"
"650px"
width
Width of the open chat window (CSS length). Overrides the console width/height setting.
"376px"
"376px"
borderRadius
Corner rounding of the chat window (CSS length).
"20px"
"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%"
"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"
"#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"
Embedded Widget
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:
Every key in the block is documented below.
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.1
"Chat"
"Chat with us"
header.subtitleText
Smaller text under the title.
not set
"We reply in minutes"
header.backgroundColor
Header background color.1
"#605dec"
"#605dec"
header.textColor
Header text color.1
"#F0F0F0"
"#FFFFFF"
header.fontFamily
Header font.1
Calibri stack
"Arial"
header.logo
Logo image in the header (URL).1
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"
1 The embedded header is off by default. When you provide a header, any fields you omit fall back to the default values.
Widget Theme
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:
Every key in the block is documented below.
hyperlinkColor
Color of links inside bot messages and notifications.
"#2196f3"
"#2196f3"
primaryFontSize
Base font size across the widget UI (number = px).
16
16
actionButtonBackground
Background of action buttons (suggested actions, adaptive cards, end-live-chat, confirmation).
"#CED6F7"
"#CED6F7"
actionButtonTextColor
Text/label color of those action buttons.
"#263398"
"#263398"
actionButtonBorderRadius
Corner rounding of action buttons.
"6px"
"6px"
messageReactionButtonColor
Color of the thumbs-up/down reaction icons on bot messages.
"#605dec"
"#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"
"#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"
"#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
275
carouselCardSpacing
Gap between carousel cards (number = px). Ignored when the bubble widget is ≤410px wide.
45
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
accent
Main accent color used across the chat.
"#605dec"
"#605dec"
backgroundColor
Transcript (chat) background color.
"White"
"White"
subtle
Color for secondary/faint text and icons.
"#909090"
"#909090"
paddingRegular
Standard padding inside components (px).
12
12
paddingWide
Wider padding, used for suggested-action buttons (px).
24
24
transitionDuration
Duration of visual transitions.
"0s"
"0.2s"
rootHeight
Height of the chat root container.
"100%"
"100%"
rootWidth
Width of the chat root container.
"100%"
"100%"
rootZIndex
Stacking order of the root container.
0
0
maxMessageLength
Most characters a visitor can type in one message.
2000
2000
messageActivityWordBreak
Word-break for message text: normal, break-all, break-word, keep-all.
"break-word"
"break-word"
Fonts & Markdown
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
true
markdownRenderHTML
Allow HTML inside Markdown messages.
true
true
markdownExternalLinkIconImage
Icon shown next to external links.
built-in icon
"url(…)"
Message Bubbles
bubbleBackground
Bot bubble background.
"#ECEFF1"
"#ECEFF1"
bubbleBorderColor
Bot bubble border color.
"#ECEFF1"
"#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"
"solid"
bubbleBorderWidth
Bot bubble border width.
0
1
bubbleTextColor
Bot bubble text color.
"#333"
"#333"
bubbleFromUserBackground
Visitor bubble background.
"#E8EAFD"
"#E8EAFD"
bubbleFromUserBorderColor
Visitor bubble border color.
"#E8EAFD"
"#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"
"solid"
bubbleFromUserBorderWidth
Visitor bubble border width.
0
1
bubbleFromUserTextColor
Visitor bubble text color.
"#0D1C8C"
"#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
240
bubbleMaxWidth
Maximum bubble width (px).
480
480
bubbleMinWidth
Minimum bubble width (px).
250
250
bubbleMinHeight
Minimum bubble height (px).
40
40
Avatars
avatarSize
Height/width of avatars (px).
32
32
avatarBorderRadius
Avatar corner rounding (50% = circle).
"50%"
"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"
"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"
"White"
userAvatarInitials
Letters shown when no visitor image.
""
"JD"
Send Box
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"
"White"
sendBoxTextColor
Text color while typing.
"#333"
"#333"
sendBoxHeight
Send box height (px).
52
52
sendBoxMaxHeight
Send box maximum height (px).
200
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"
"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"
"#333"
sendBoxButtonColorOnFocus
Button icon color on focus.
"#333"
"#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"
"transparent"
sendBoxButtonShadeColorOnHover
Shade on hover.
"transparent"
"#F3F2F1"
sendBoxButtonShadeColorOnFocus
Shade on focus.
"transparent"
"transparent"
sendBoxButtonShadeColorOnActive
Shade while active.
"transparent"
"#EDEBE9"
sendBoxButtonShadeColorOnDisabled
Shade when disabled.
"transparent"
"#F3F2F1"
sendBoxButtonShadeBorderRadius
Corner rounding of the button shade.
2
2
sendBoxButtonShadeInset
Inset of the button shade.
2
2
sendBoxButtonAlignment
Vertical alignment of send box buttons: stretch, top, bottom.
"stretch"
"stretch"
microphoneButtonColorOnDictate
Microphone color while recording.
"#F33"
"#F33"
showSpokenText
Visually show spoken text.
true
true
sendAttachmentOn
When files are sent: attach (immediately) or send.
"attach"
"attach"
uploadAccept
Which file types the upload button accepts.
not set
"image/*"
uploadMultiple
Allow selecting several files at once.
true
true
Suggested Action Buttons
suggestedActionLayout
Layout: carousel, flow, or stacked.
"carousel"
"stacked"
suggestedActionBackgroundColor
Button background.
"White"
"White"
suggestedActionTextColor
Button text color.
not set (uses accent)
"#605dec"
suggestedActionBorderColor
Button border color.
not set (uses accent)
"#605dec"
suggestedActionBorderStyle
Button border style.
"solid"
"solid"
suggestedActionBorderWidth
Button border width.
2
2
suggestedActionBorderRadius
Button corner rounding.
"6px"
"6px"
suggestedActionHeight
Button height (px).
40
40
suggestedActionImageHeight
Image height inside buttons (px).
20
20
suggestedActionBackgroundColorOnHover
Background on hover.
"White"
"White"
suggestedActionBackgroundColorOnFocus
Background on focus.
"White"
"White"
suggestedActionBackgroundColorOnActive
Background while active.
"White"
"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"
"#E6E6E6"
suggestedActionBorderStyleOnDisabled
Border style when disabled.
"solid"
"solid"
suggestedActionBorderWidthOnDisabled
Border width when disabled.
2
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
40
suggestedActionsCarouselFlipperSize
Carousel scroll-arrow visible size (px).
20
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
240
suggestedActionsStackedHeight
Max height of the button area in stacked layout.
240
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
groupTimestamp
Group messages under one timestamp: true/false/number (ms window).
true
300000
timestampFormat
Time display: relative or absolute.
"relative"
"relative"
timestampColor
Timestamp text color.
not set (uses subtle)
"#999"
sendTimeout
Time (ms) before a message is marked failed.
20000
20000
sendTimeoutForAttachments
Same, for file attachments (ms).
120000
120000
Toasts & Notifications
hideToaster
Hide all toast banners.
true
false
notificationDebounceTimeout
Delay (ms) to avoid flickering notifications.
400
400
notificationText
Color of small notification text.
"#5E5E5E"
"#5E5E5E"
toasterHeight
Toaster height (px).
32
32
toasterMaxHeight
Toaster max height (px).
160
160
toasterSingularMaxHeight
Single-toast max height (px).
50
50
toastFontSize
Toast text size.
"87.5%"
"87.5%"
toastIconWidth
Toast icon width (px).
36
36
toastTextPadding
Toast text padding (px).
6
6
toastSeparatorColor
Toast separator color.
"#E8EAEC"
"#E8EAEC"
toastInfoBackgroundColor / toastInfoColor
Info toast background / text.
"#605dec" / "white"
"#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
slowConnectivity
Color for the "slow connection" status.
"#EAA300"
"#EAA300"
failedConnectivity
Color for the "connection failed" status.
"#C50F1F"
"#C50F1F"
slowConnectionAfter
Wait (ms) before showing "slow".
15000
15000
connectivityTextSize
Status text size.
"75%"
"75%"
connectivityIconPadding
Padding around the status icon (px).
14.4
14.4
connectivityMarginLeftRight
Left/right margin of the status (px).
16.8
16.8
connectivityMarginTopBottom
Top/bottom margin of the status (px).
9.6
9.6
Scroll-To-End Button
scrollToEndButtonBehavior
When it shows: unread, any, or false (never).
"unread"
"unread"
scrollToEndButtonFontSize
Button text size.
16
16
autoScrollSnapOnActivity
Pause auto-scroll after N activities (true/false/number).
false
true
autoScrollSnapOnActivityOffset
Over/underscroll (px) after activity snap.
0
0
autoScrollSnapOnPage
Pause auto-scroll after page fill (true/false/fraction).
false
true
autoScrollSnapOnPageOffset
Over/underscroll (px) after page snap.
0
0
newMessagesButtonFontSize
(DEPRECATED) Renamed to scrollToEndButtonFontSize.
not set
—
Typing & Loading Animations
typingAnimationDuration
How long the "typing…" animation shows (ms).
5000
5000
typingAnimationHeight
Typing animation height (px).
35
35
typingAnimationWidth
Typing animation width (px).
53
53
typingAnimationBackgroundImage
Custom image for the typing animation.
built-in animation
"url(…)"
spinnerAnimationHeight
Loading spinner height (px).
16
16
spinnerAnimationWidth
Loading spinner width (px).
16
16
spinnerAnimationPadding
Loading spinner padding (px).
12
12
spinnerAnimationBackgroundImage
Custom image for the loading spinner.
not set
"url(…)"
Uploads & Video
enableUploadThumbnail
Create a small preview for uploaded images.
true
true
uploadThumbnailWidth
Preview width (px).
720
720
uploadThumbnailHeight
Preview height (px).
360
360
uploadThumbnailQuality
Preview image quality (0–1).
0.6
0.6
uploadThumbnailContentType
Preview image format.
"image/jpeg"
"image/jpeg"
videoHeight
Height of videos shown in chat (px).
270
270
Transcript & Overlay Buttons
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"
"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"
"#595959"
transcriptTerminatorColor
Text color of that divider.
"White"
"White"
transcriptTerminatorFontSize
Text size of that divider (px).
12
12
transcriptTerminatorBorderRadius
Corner rounding of that divider.
5
5
Emoji
emojiSet
Enable the built-in emoji set (true) or supply a custom emoticon→emoji map.
true
true
Accessibility & Keyboard Focus
Rarely changed. They style focus outlines during keyboard navigation.
internalLiveRegionFadeAfter
How long (ms) screen-reader announcements stay before fading.
1000
1000
sendBoxButtonKeyboardFocusIndicatorBorderColor
Focus outline color on send box buttons.
"#605E5C"
"#605E5C"
sendBoxButtonKeyboardFocusIndicatorBorderStyle
Focus outline style on send box buttons.
"solid"
"solid"
sendBoxButtonKeyboardFocusIndicatorBorderWidth
Focus outline width on send box buttons.
1
1
sendBoxButtonKeyboardFocusIndicatorBorderRadius
Focus outline radius on send box buttons.
0
0
sendBoxButtonKeyboardFocusIndicatorInset
Focus outline inset on send box buttons.
4
4
suggestedActionKeyboardFocusIndicatorBorderColor
Focus outline color on suggested actions.
"#605E5C"
"#605E5C"
suggestedActionKeyboardFocusIndicatorBorderStyle
Focus outline style on suggested actions.
"dashed"
"dashed"
suggestedActionKeyboardFocusIndicatorBorderWidth
Focus outline width on suggested actions.
1
1
suggestedActionKeyboardFocusIndicatorBorderRadius
Focus outline radius on suggested actions.
0
0
suggestedActionKeyboardFocusIndicatorInset
Focus outline inset on suggested actions.
2
2
suggestedActionsVisualKeyboardIndicatorColor
Outline color on a focused suggested action.
"Black"
"Black"
suggestedActionsVisualKeyboardIndicatorStyle
Outline style on a focused suggested action.
"solid"
"solid"
suggestedActionsVisualKeyboardIndicatorWidth
Outline width on a focused suggested action.
2
2
transcriptVisualKeyboardIndicatorColor
Outline color around the focused transcript.
"Black"
"Black"
transcriptVisualKeyboardIndicatorStyle
Outline style around the focused transcript.
"solid"
"solid"
transcriptVisualKeyboardIndicatorWidth
Outline width around the focused transcript.
0
0
transcriptActivityVisualKeyboardIndicatorColor
Outline color around a focused message.
"#909090"
"#909090"
transcriptActivityVisualKeyboardIndicatorStyle
Outline style around a focused message.
"dashed"
"dashed"
transcriptActivityVisualKeyboardIndicatorWidth
Outline width around a focused message.
0
0
You can now configure any part of the Webchat widget through Custom Settings, from connection and behavior to its full visual theme.
Last updated