> For the complete documentation index, see [llms.txt](https://docs.helvia.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helvia.ai/deploy/webchat/custom-settings.md).

# 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 Layout Setting. 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:

<details open>

<summary><i class="fa-layer-group">:layer-group:</i> <strong>Custom Settings take priority</strong></summary>

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.

</details>

<details>

<summary><i class="fa-circle-check">:circle-check:</i> <strong>Your input is checked as you type</strong></summary>

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.

</details>

<details>

<summary><i class="fa-shapes">:shapes:</i> <strong>Two widget modes: Bubble and Embedded</strong></summary>

The widget runs in one of two modes, set by `widgetStyle`: Bubble (a floating launcher button that opens a chat window) or Embedded (the chat placed directly in the page). Some settings apply to only one mode.

</details>

<details>

<summary><i class="fa-brackets-curly">:brackets-curly:</i> <strong>Set several values at once</strong></summary>

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.

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

</details>

<details>

<summary><i class="fa-list">:list:</i> <strong>List settings replace, they do not merge</strong></summary>

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.

</details>

<details>

<summary><i class="fa-microchip">:microchip:</i> <strong>Powered by Microsoft Bot Framework Web Chat</strong></summary>

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.

</details>

### 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.&#x20;

<div data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2F188b5ciTwkhCAVFSpfC9%2FSCR-20260817-obor.png?alt=media&amp;token=794203aa-7c04-4eac-9f09-dcf1313e15ef" alt="" width="563"><figcaption></figcaption></figure></div>

{% hint style="info" %}
**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.
{% endhint %}

### 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 the same columns: the `Key`, a `Description`, the `Default` applied when you leave the key unset, and an `Example` value.

<table data-column-title-hidden data-view="cards"><thead><tr><th>Section</th><th>Description</th></tr></thead><tbody><tr><td><h4><i class="fa-sliders">:sliders:</i></h4><h4>Core Settings</h4></td><td>Root-level keys that control how the widget connects and behaves</td></tr><tr><td><h4><i class="fa-window-maximize">:window-maximize:</i></h4><h4>Widget Style</h4></td><td>Everything under <code>widgetStyleSet</code>: the launcher, window, header, and pop-ups</td></tr><tr><td><h4><i class="fa-palette">:palette:</i></h4><h4>Widget Theme</h4></td><td>Everything under <code>styleSetOptions</code>: colors, fonts, and bubbles inside the chat</td></tr></tbody></table>

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

* **(BLOCKED):** System-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:

```jsonc
{
  // ── 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.

<table><thead><tr><th width="160">Key</th><th width="340">Description</th><th width="100">Default</th><th>Example</th></tr></thead><tbody><tr><td><code>id</code></td><td><strong>(BLOCKED)</strong> Unique webchat id (UUIDv4); platform-set.</td><td><code>""</code></td><td><code>"a1b2c3d4-…"</code></td></tr><tr><td><code>tokenURL</code></td><td><strong>(BLOCKED)</strong> DirectLine token endpoint; platform-set.</td><td><code>""</code></td><td><code>"https://…/token"</code></td></tr><tr><td><code>azureSpeechTokenURL</code></td><td>Speech token endpoint URL; an empty string is ignored.</td><td><code>""</code></td><td><code>"https://…/speech"</code></td></tr><tr><td><code>azureSpeechSynthesisDeploymentId</code></td><td>Text-to-speech voice deployment id (advanced).</td><td><code>""</code></td><td><code>"deploy-123"</code></td></tr><tr><td><code>domain</code></td><td>DirectLine service address override (advanced).</td><td>not set</td><td><code>"https://…/v3/directline"</code></td></tr><tr><td><code>secret</code></td><td>DirectLine secret; also lets <code>bot</code> be set here.</td><td>not set</td><td><code>"abc123"</code></td></tr><tr><td><code>bot.id</code></td><td><strong>(BLOCKED unless <code>secret</code> set)</strong> Bot internal id.</td><td><code>""</code></td><td><code>"bot-001"</code></td></tr><tr><td><code>bot.name</code></td><td><strong>(BLOCKED unless <code>secret</code> set)</strong> Bot display name.</td><td><code>""</code></td><td><code>"Support Bot"</code></td></tr><tr><td><code>bot.role</code></td><td><strong>(BLOCKED unless <code>secret</code> set)</strong> Bot role label.</td><td><code>"bot"</code></td><td><code>"bot"</code></td></tr><tr><td><code>user.name</code></td><td>Visitor's display name.</td><td><code>"Webchat User"</code></td><td><code>"Jane"</code></td></tr><tr><td><code>user.id</code></td><td>Visitor id; usually set from the session.</td><td><code>""</code></td><td><code>"user-789"</code></td></tr><tr><td><code>botDivId</code></td><td>Id of the page element the widget mounts into.</td><td><code>"botDiv"</code></td><td><code>"myChat"</code></td></tr><tr><td><code>locale</code></td><td>Starting language code.</td><td><code>"en"</code></td><td><code>"el"</code></td></tr><tr><td><code>supportedLocales</code></td><td>Languages the visitor can pick from.</td><td><code>["en"]</code></td><td><code>["en", "el"]</code></td></tr><tr><td><code>showLocaleSelector</code></td><td>Show a language picker.</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>sessionDuration</code></td><td>Days a chat session stays valid.</td><td><code>365</code></td><td><code>30</code></td></tr><tr><td><code>keepTranscript</code></td><td>Keep transcript in memory while the page is open (needed for <code>getTranscript()</code>).</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>messageHistory.enabled</code></td><td>Reload previous messages when the visitor returns.</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>messageHistory.sendGreetingMessage</code></td><td>Re-send the greeting when history reloads.</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>messageHistory.maxNumberOfMessages</code></td><td>Max messages to reload; <code>0</code> disables reload.</td><td><code>100</code></td><td><code>50</code></td></tr><tr><td><code>messageHistory.maxNumberOfSessions</code></td><td>Past sessions to reload; <code>0</code> = all sessions.</td><td><code>1</code></td><td><code>3</code></td></tr><tr><td><code>entryPoint</code></td><td>Node used as the greeting/entry; usually set from the deployment.</td><td>not set</td><td><code>"node-welcome"</code></td></tr><tr><td><code>greetingMessages</code></td><td>Auto messages when the chat opens (replace-array).</td><td>not set</td><td>(rows below)</td></tr><tr><td><code>greetingMessages[].conversationNodeId</code></td><td>Bot flow node to trigger as the greeting.</td><td>not set</td><td><code>"node-welcome"</code></td></tr><tr><td><code>greetingMessages[].quick</code></td><td>Pre-built messages or quick-reply buttons.</td><td>not set</td><td>—</td></tr><tr><td><code>greetingMessages[].triggerWhenInactiveFor</code></td><td>Seconds of inactivity before sending.</td><td>required</td><td><code>0</code></td></tr><tr><td><code>startUpNotifications</code></td><td><strong>(UI)</strong> Banners shown on load (replace-array).</td><td>not set</td><td>(rows below)</td></tr><tr><td><code>startUpNotifications[].text</code></td><td>Notification message (optional; image-only is allowed).</td><td>not set</td><td><code>"We're online!"</code></td></tr><tr><td><code>startUpNotifications[].level</code></td><td>Severity: <code>ERROR</code>, <code>INFO</code>, <code>SUCCESS</code>, <code>WARN</code>.</td><td>required</td><td><code>"INFO"</code></td></tr><tr><td><code>startUpNotifications[].id</code></td><td>Optional internal id.</td><td>not set</td><td><code>"n1"</code></td></tr><tr><td><code>startUpNotifications[].hasSound</code></td><td>Play a sound with the notification.</td><td>not set</td><td><code>true</code></td></tr><tr><td><code>startUpNotifications[].imageUrl</code></td><td>Image to show.</td><td>not set</td><td><code>"https://…/promo.png"</code></td></tr><tr><td><code>startUpNotifications[].imageLink</code></td><td>Page opened when the image is clicked.</td><td>not set</td><td><code>"https://example.com"</code></td></tr><tr><td><code>startUpNotifications[].buttons[].type</code></td><td><code>DISMISS</code> (close) or <code>HCN</code> (trigger a bot flow).</td><td>required</td><td><code>"HCN"</code></td></tr><tr><td><code>startUpNotifications[].buttons[].title</code></td><td>Button label.</td><td>required</td><td><code>"Talk to us"</code></td></tr><tr><td><code>startUpNotifications[].buttons[].conversationNodeId</code></td><td>Flow node to trigger (for an <code>HCN</code> button).</td><td>required for <code>HCN</code></td><td><code>"node-start"</code></td></tr><tr><td><code>idleNotifications</code></td><td><strong>(UI)</strong> Banners shown after inactivity (replace-array).</td><td>not set</td><td>(rows below)</td></tr><tr><td><code>idleNotifications[].text</code></td><td>Notification message (required for idle).</td><td>required</td><td><code>"Still there?"</code></td></tr><tr><td><code>idleNotifications[].level</code></td><td>Severity: <code>ERROR</code>, <code>INFO</code>, <code>SUCCESS</code>, <code>WARN</code>.</td><td>required</td><td><code>"INFO"</code></td></tr><tr><td><code>idleNotifications[].id</code></td><td>Optional internal id.</td><td>not set</td><td><code>"n2"</code></td></tr><tr><td><code>idleNotifications[].hasSound</code></td><td>Play a sound with the notification.</td><td>not set</td><td><code>true</code></td></tr><tr><td><code>idleNotifications[].imageUrl</code></td><td>Image to show.</td><td>not set</td><td><code>"https://…/promo.png"</code></td></tr><tr><td><code>idleNotifications[].imageLink</code></td><td>Page opened when the image is clicked.</td><td>not set</td><td><code>"https://example.com"</code></td></tr><tr><td><code>idleNotifications[].buttons[].type</code></td><td><code>DISMISS</code> (close) or <code>HCN</code> (trigger a bot flow).</td><td>required</td><td><code>"HCN"</code></td></tr><tr><td><code>idleNotifications[].buttons[].title</code></td><td>Button label.</td><td>required</td><td><code>"Talk to us"</code></td></tr><tr><td><code>idleNotifications[].buttons[].conversationNodeId</code></td><td>Flow node to trigger (for an <code>HCN</code> button).</td><td>required for <code>HCN</code></td><td><code>"node-start"</code></td></tr><tr><td><code>idleNotifications[].triggerWhenInactiveFor</code></td><td>Seconds of inactivity before showing.</td><td>required</td><td><code>60</code></td></tr><tr><td><code>idleNotifications[].triggerConversationNodeId</code></td><td>Optional bot flow node to trigger.</td><td>not set</td><td><code>"node-idle"</code></td></tr><tr><td><code>messageSoundNotifications</code></td><td>Play sounds for <code>all</code> messages or only <code>livechat</code> (agent) messages.</td><td>not set</td><td><code>"livechat"</code></td></tr><tr><td><code>idleReminderMessages</code></td><td><strong>(DEPRECATED)</strong> Use <code>idleNotifications</code> instead.</td><td>not set</td><td>—</td></tr><tr><td><code>disableSendBoxOnStart</code></td><td>Lock the input box when the chat opens.</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>startupNotificationsRequireDismissal</code></td><td>Lock input until a start-up notification is dismissed.</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>disableSendBoxOnSuggestedActions</code></td><td>Lock typing when buttons or cards are shown.</td><td><code>true</code></td><td><code>false</code></td></tr><tr><td><code>disableSendBoxOnCards</code></td><td>Lock typing only when cards are shown.</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>disableSendBoxAfterMessageDuration</code></td><td>Lock typing for N milliseconds after a message is sent.</td><td>not set</td><td><code>2000</code></td></tr><tr><td><code>keepCardButtonsEnabledAfterClick</code></td><td>Keep card buttons clickable after a click.</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>maxFileSizeForUpload</code></td><td>Largest uploadable file, in bytes (4194304 = 4 MB).</td><td><code>4194304</code></td><td><code>8388608</code></td></tr><tr><td><code>enableFileUploadOnDemand</code></td><td>Allow uploads only when the bot asks for a file.</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>fileTooLargeConversationNodeId</code></td><td><strong>(DEPRECATED)</strong> Node when a file is too big; handle in the flow instead.</td><td>not set</td><td><code>"node-toobig"</code></td></tr><tr><td><code>allowSpeechToText</code></td><td><strong>(UI)</strong> Enable the microphone (speech-to-text).</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>ttsVoiceName</code></td><td>Azure text-to-speech voice used to read messages aloud.</td><td>not set</td><td><code>"en-US-JennyNeural"</code></td></tr><tr><td><code>ttsLexiconUrl</code></td><td>URL of an Azure custom lexicon (PLS/XML) for text-to-speech pronunciation.</td><td>not set</td><td><code>"https://…/lexicon.xml"</code></td></tr><tr><td><code>speechSubscriptionKey</code></td><td>Azure Speech key (advanced).</td><td>not set</td><td><code>"key-123"</code></td></tr><tr><td><code>speechRegion</code></td><td>Azure Speech region (advanced).</td><td>not set</td><td><code>"eastus"</code></td></tr><tr><td><code>sttReplacements</code></td><td>Find/replace rules applied to dictated speech only.</td><td><code>[]</code></td><td>(rows below)</td></tr><tr><td><code>sttReplacements[].match</code></td><td>Text to find, written as a regular expression.</td><td>required</td><td><code>"acme"</code></td></tr><tr><td><code>sttReplacements[].replacement</code></td><td>Written form that replaces each match.</td><td>required</td><td><code>"ACME"</code></td></tr><tr><td><code>sttReplacements[].flags</code></td><td>Extra regex flags, e.g. <code>"i"</code> for case-insensitive.</td><td>not set</td><td><code>"i"</code></td></tr><tr><td><code>sttReplacements[].wholeWord</code></td><td>Match only as a standalone word.</td><td><code>true</code></td><td><code>false</code></td></tr><tr><td><code>widgetStyle</code></td><td><strong>(UI)</strong> <code>BUBBLE</code> (floating button) or <code>EMBEDDED</code> (in-page). Also selects the <code>widgetStyleSet</code> shape.</td><td><code>"BUBBLE"</code></td><td><code>"EMBEDDED"</code></td></tr><tr><td><code>linkTarget</code></td><td>Where chat links open: <code>_blank</code> (new tab) or <code>_self</code> (same tab).</td><td><code>"_blank"</code></td><td><code>"_self"</code></td></tr><tr><td><code>showErrorFallback</code></td><td>Show a fallback message if the widget fails to load.</td><td>not set</td><td><code>true</code></td></tr><tr><td><code>sendUserLeftEvent</code></td><td>Notify the bot when the visitor leaves the page.</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>customFunctionsIntervalTime</code></td><td>Seconds between custom-function runs; <code>0</code> = run once.</td><td><code>0</code></td><td><code>30</code></td></tr><tr><td><code>invokeCustomFunctionsOnBeforeMessages</code></td><td>Run custom functions before messages are sent.</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>retrieveUserIdFromLogin</code></td><td><strong>(BLOCKED)</strong> Read the visitor id from login; use <code>window.HBF_retrieveUserId</code>.</td><td>built-in</td><td>—</td></tr><tr><td><code>retrieveUserInfoFromLogin</code></td><td><strong>(BLOCKED)</strong> Read visitor details from login; use <code>window.HBF_retrieveUserInfo</code>.</td><td>built-in</td><td>—</td></tr><tr><td><code>retrieveMetadata</code></td><td><strong>(BLOCKED)</strong> Attach extra data to the chat; use <code>window.HBF_retrieveMetadata</code>.</td><td>built-in</td><td>—</td></tr></tbody></table>

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

```jsonc
{
  "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.

<table><thead><tr><th width="159.5">Key</th><th width="359.5">Description</th><th width="110">Default</th><th>Example</th></tr></thead><tbody><tr><td><code>color</code></td><td>Launcher button color.</td><td><code>"#605dec"</code></td><td><code>"#605dec"</code></td></tr><tr><td><code>height</code></td><td>Height of the open chat window (CSS length). Overrides the Console width/height setting.</td><td><code>"650px"</code></td><td><code>"650px"</code></td></tr><tr><td><code>width</code></td><td>Width of the open chat window (CSS length). Overrides the console width/height setting.</td><td><code>"376px"</code></td><td><code>"376px"</code></td></tr><tr><td><code>borderRadius</code></td><td>Corner rounding of the chat window (CSS length).</td><td><code>"20px"</code></td><td><code>"20px"</code></td></tr><tr><td><code>fabIconOpen</code></td><td>Icon shown when the chat is closed (URL).</td><td>not set</td><td><code>"https://…/open.svg"</code></td></tr><tr><td><code>fabIconClose</code></td><td>Icon shown when the chat is open (URL).</td><td>not set</td><td><code>"https://…/close.svg"</code></td></tr><tr><td><code>fabIconPadding</code></td><td>Space around the launcher icon; number = px, string = any CSS length.</td><td><code>"25%"</code></td><td><code>"25%"</code></td></tr><tr><td><code>fabButtonBorder</code></td><td>Thickness of the button's outer ring; number = px.</td><td><code>5</code></td><td><code>0</code></td></tr><tr><td><code>fabAnimation.variant</code></td><td>Launcher animation: <code>pulse</code>, <code>bounce</code>, or <code>none</code>.</td><td><code>"pulse"</code></td><td><code>"bounce"</code></td></tr><tr><td><code>fabAnimation.durationMs</code></td><td>One animation cycle length, in ms.</td><td><code>1000</code> pulse / <code>1400</code> bounce</td><td><code>1400</code></td></tr><tr><td><code>fabAnimation.iterationCount</code></td><td>How many times it repeats; number or <code>"infinite"</code>.</td><td><code>5</code></td><td><code>"infinite"</code></td></tr><tr><td><code>fabHoverAnimation</code></td><td>Hover effect: <code>zoom</code> or <code>none</code>.</td><td>not set</td><td><code>"zoom"</code></td></tr><tr><td><code>fabOpenCloseIconAnimation</code></td><td>Open/close icon switch effect: <code>rotate</code> or <code>none</code>.</td><td>not set</td><td><code>"rotate"</code></td></tr><tr><td><code>pulse</code></td><td><strong>(DEPRECATED)</strong> Old launcher pulse; use <code>fabAnimation</code> instead.</td><td>not set</td><td>—</td></tr><tr><td><code>tooltip</code></td><td>Message shown over the launcher button.</td><td>not set</td><td><code>"Need help?"</code></td></tr><tr><td><code>header.text</code></td><td>Header title.</td><td><code>"Chat"</code></td><td><code>"Chat with us"</code></td></tr><tr><td><code>header.subtitleText</code></td><td>Smaller text under the title (supports links).</td><td>Helvia.ai credit</td><td><code>"We reply in minutes"</code></td></tr><tr><td><code>header.showSubtitle</code></td><td>Show or hide the subtitle.</td><td><code>true</code></td><td><code>false</code></td></tr><tr><td><code>header.backgroundColor</code></td><td>Header background color.</td><td><code>"#605dec"</code></td><td><code>"#605dec"</code></td></tr><tr><td><code>header.textColor</code></td><td>Header text color.</td><td><code>"#F0F0F0"</code></td><td><code>"#FFFFFF"</code></td></tr><tr><td><code>header.fontFamily</code></td><td>Header font.</td><td>Calibri stack</td><td><code>"Arial"</code></td></tr><tr><td><code>header.logo</code></td><td>Logo image in the header (URL).</td><td>default Helvia avatar</td><td><code>"https://…/logo.png"</code></td></tr><tr><td><code>header.headerStyle</code></td><td>Header layout: <code>center</code> or <code>left</code>.</td><td><code>"center"</code></td><td><code>"left"</code></td></tr><tr><td><code>header.headerBorderRadius</code></td><td>Header corner rounding; number = px or CSS length.</td><td>not set</td><td><code>"10px"</code></td></tr><tr><td><code>header.headerHeight</code></td><td>Header height; number = px or CSS length.</td><td>not set</td><td><code>"60px"</code></td></tr><tr><td><code>header.headerMargin</code></td><td>Space around the header; number = px or CSS length.</td><td>not set</td><td><code>"0"</code></td></tr><tr><td><code>autoPopOut.enable</code></td><td>Open the chat automatically after a delay.</td><td>not set (off)</td><td><code>true</code></td></tr><tr><td><code>autoPopOut.delayInSeconds</code></td><td>Seconds to wait before opening.</td><td>not set</td><td><code>5</code></td></tr><tr><td><code>autoPopOut.extendTimeAfterView</code></td><td>Reset the timer after the visitor has seen it.</td><td>not set</td><td><code>true</code></td></tr><tr><td><code>autoPopOut.once</code></td><td>Only open automatically once per visitor.</td><td>not set</td><td><code>true</code></td></tr><tr><td><code>userPromptBubble.enable</code></td><td>Show a small invite bubble by the launcher.</td><td>not set (off)</td><td><code>true</code></td></tr><tr><td><code>userPromptBubble.delayInSeconds</code></td><td>Seconds before showing it.</td><td>not set</td><td><code>3</code></td></tr><tr><td><code>userPromptBubble.message</code></td><td>Text in the bubble.</td><td>not set</td><td><code>"Hi! Need any help?"</code></td></tr><tr><td><code>advancedChatPromptBubble.enable</code></td><td>Two-step invite bubble that can offer channels.</td><td>not set (off)</td><td><code>true</code></td></tr><tr><td><code>advancedChatPromptBubble.stepOneMessage</code></td><td>First message shown.</td><td>not set</td><td><code>"Hello!"</code></td></tr><tr><td><code>advancedChatPromptBubble.stepOneButtonLabel</code></td><td>Button to go to step two.</td><td>not set</td><td><code>"Chat now"</code></td></tr><tr><td><code>advancedChatPromptBubble.stepTwoMessage</code></td><td>Second message shown.</td><td>not set</td><td><code>"Pick a channel:"</code></td></tr><tr><td><code>advancedChatPromptBubble.deployments[].icon</code></td><td>Channel icon (URL).</td><td>not set</td><td><code>"https://…/whatsapp.png"</code></td></tr><tr><td><code>advancedChatPromptBubble.deployments[].url</code></td><td>Optional link for that channel.</td><td>not set</td><td><code>"https://wa.me/…"</code></td></tr><tr><td><code>hcnButtons[].conversationNodeId</code></td><td>Bot flow node the button triggers.</td><td>required</td><td><code>"node-order-status"</code></td></tr><tr><td><code>hcnButtons[].title</code></td><td>Button label.</td><td>required</td><td><code>"Track my order"</code></td></tr><tr><td><code>hcnButtons[].language</code></td><td>Optional language for the button.</td><td>not set</td><td><code>"en"</code></td></tr><tr><td><code>hcnButtons[].icon</code></td><td>Optional button icon (URL).</td><td>not set</td><td><code>"https://…/track.png"</code></td></tr></tbody></table>

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

```jsonc
{
  "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.

<table><thead><tr><th width="175.5">Key</th><th width="299.5">Description</th><th width="118.5">Default</th><th>Example</th></tr></thead><tbody><tr><td><code>borderRadius</code></td><td>Corner rounding of the embedded chat (CSS length).</td><td><code>"20px"</code></td><td><code>"25px"</code></td></tr><tr><td><code>appendOnBodyAsFallback</code></td><td>If its container is missing, attach the chat to the page body instead.</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>header.text</code></td><td>Header title.<sup>1</sup></td><td><code>"Chat"</code> </td><td><code>"Chat with us"</code></td></tr><tr><td><code>header.subtitleText</code></td><td>Smaller text under the title.</td><td>not set</td><td><code>"We reply in minutes"</code></td></tr><tr><td><code>header.backgroundColor</code></td><td>Header background color.<sup>1</sup></td><td><code>"#605dec"</code> </td><td><code>"#605dec"</code></td></tr><tr><td><code>header.textColor</code></td><td>Header text color.<sup>1</sup></td><td><code>"#F0F0F0"</code> </td><td><code>"#FFFFFF"</code></td></tr><tr><td><code>header.fontFamily</code></td><td>Header font.<sup>1</sup></td><td>Calibri stack</td><td><code>"Arial"</code></td></tr><tr><td><code>header.logo</code></td><td>Logo image in the header (URL).<sup>1</sup></td><td>default Helvia avatar</td><td><code>"https://…/logo.png"</code></td></tr><tr><td><code>footer.text</code></td><td>Footer text (supports links).</td><td>Helvia.ai credit</td><td><code>"Powered by helvia.ai"</code></td></tr><tr><td><code>footer.fontFamily</code></td><td>Footer font.</td><td>not set</td><td><code>"Arial"</code></td></tr><tr><td><code>hcnButtons[].conversationNodeId</code></td><td>Bot flow node the button triggers.</td><td>required</td><td><code>"node-menu"</code></td></tr><tr><td><code>hcnButtons[].title</code></td><td>Button label.</td><td>required</td><td><code>"Menu"</code></td></tr><tr><td><code>hcnButtons[].language</code></td><td>Optional language for the button.</td><td>not set</td><td><code>"en"</code></td></tr><tr><td><code>hcnButtons[].icon</code></td><td>Optional button icon (URL).</td><td>not set</td><td><code>"https://…/i.png"</code></td></tr></tbody></table>

<sup>1</sup> 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:

```jsonc
{
  "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.

<table><thead><tr><th width="155.5">Key</th><th width="400.5">Description</th><th width="105">Default</th><th>Example</th></tr></thead><tbody><tr><td><code>hyperlinkColor</code></td><td>Color of links inside bot messages and notifications.</td><td><code>"#2196f3"</code></td><td><code>"#2196f3"</code></td></tr><tr><td><code>primaryFontSize</code></td><td>Base font size across the widget UI (number = px).</td><td><code>16</code></td><td><code>16</code></td></tr><tr><td><code>actionButtonBackground</code></td><td>Background of action buttons (suggested actions, adaptive cards, end-live-chat, confirmation).</td><td><code>"#CED6F7"</code></td><td><code>"#CED6F7"</code></td></tr><tr><td><code>actionButtonTextColor</code></td><td>Text/label color of those action buttons.</td><td><code>"#263398"</code></td><td><code>"#263398"</code></td></tr><tr><td><code>actionButtonBorderRadius</code></td><td>Corner rounding of action buttons.</td><td><code>"6px"</code></td><td><code>"6px"</code></td></tr><tr><td><code>messageReactionButtonColor</code></td><td>Color of the thumbs-up/down reaction icons on bot messages.</td><td><code>"#605dec"</code></td><td><code>"#605dec"</code></td></tr><tr><td><code>hideEmojiPickerButton</code></td><td>Hide the emoji-picker button in the send box.</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>csatMainColor</code></td><td>Primary accent of the CSAT survey popup (backgrounds, borders, selected stars, close icon).</td><td><code>"#605dec"</code></td><td><code>"#605dec"</code></td></tr><tr><td><code>csatFontColor</code></td><td>Text color inside the CSAT popup.</td><td>not set (uses <code>csatMainColor</code>)</td><td><code>"#333"</code></td></tr><tr><td><code>csatFontFamily</code></td><td>Font family of the CSAT popup.</td><td>Calibri stack</td><td><code>"Arial"</code></td></tr><tr><td><code>csatFontSize</code></td><td>Base font size of the CSAT popup text.</td><td>not set (uses <code>primaryFontSize</code>)</td><td><code>14</code></td></tr><tr><td><code>csatButtonFontColor</code></td><td>Text color of the CSAT submit button.</td><td><code>"#ffffff"</code></td><td><code>"#ffffff"</code></td></tr><tr><td><code>hideCsatExplanations</code></td><td>Hide the helper text under CSAT/rating options.</td><td><code>true</code></td><td><code>false</code></td></tr><tr><td><code>sendBoxHomeActionButtonEnabled</code></td><td>Add a "home" button to the send box that posts back to the bot's entry point.</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>sendBoxHomeActionButtonIconUrl</code></td><td>Custom icon (URL) for the home button; use a square (1:1) image.</td><td>not set (built-in icon)</td><td><code>"https://…/home.svg"</code></td></tr><tr><td><code>sendBoxCustomActionButtonEnabled</code></td><td>Add a second, custom action button to the send box.</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>sendBoxCustomActionButtonTriggerNodeId</code></td><td>Flow node the custom action button posts back to.</td><td>not set</td><td><code>"node-menu"</code></td></tr><tr><td><code>sendBoxCustomActionButtonIconUrl</code></td><td>Custom icon (URL) for the custom action button; use a square (1:1) image.</td><td>not set (built-in icon)</td><td><code>"https://…/star.svg"</code></td></tr><tr><td><code>sendBoxSendIcon</code></td><td>Custom SVG markup for the send button (falls back to the default arrow if invalid).</td><td>built-in arrow</td><td><code>"&#x3C;svg …>&#x3C;/svg>"</code></td></tr><tr><td><code>carouselCardWidth</code></td><td>Width of each carousel card (number = px). Ignored when the bubble widget is ≤410px wide.</td><td><code>275</code></td><td><code>275</code></td></tr><tr><td><code>carouselCardSpacing</code></td><td>Gap between carousel cards (number = px). Ignored when the bubble widget is ≤410px wide.</td><td><code>45</code></td><td><code>45</code></td></tr><tr><td><code>carouselTextColor</code></td><td>Text color inside carousel cards.</td><td><code>"inherit"</code></td><td><code>"#333"</code></td></tr><tr><td><code>carouselCardBackgroundColor</code></td><td>Carousel card background/border color.</td><td>not set (uses <code>bubbleBackground</code>)</td><td><code>"White"</code></td></tr><tr><td><code>carouselArrowBackgroundColor</code></td><td>Background of the carousel navigation arrows.</td><td>not set (uses <code>actionButtonTextColor</code>)</td><td><code>"#605dec"</code></td></tr><tr><td><code>carouselArrowColor</code></td><td>Color of the carousel arrow icons.</td><td>not set (uses <code>actionButtonBackground</code>)</td><td><code>"White"</code></td></tr><tr><td><code>carouselArrowHoverBackgroundColor</code></td><td>Arrow background on hover.</td><td>not set (uses <code>actionButtonBackground</code>)</td><td><code>"#403db0"</code></td></tr><tr><td><code>carouselArrowHoverColor</code></td><td>Arrow icon color on hover.</td><td>not set (uses <code>actionButtonTextColor</code>)</td><td><code>"White"</code></td></tr><tr><td><code>hideEndLiveChatButton</code></td><td>When explicitly <code>false</code>, shows an "End Live Chat" button on bot messages during a live chat (default <code>true</code> hides it).</td><td><code>true</code></td><td><code>false</code></td></tr><tr><td><code>terminateLivechatConfirmation</code></td><td>Custom title text in the "end live chat" confirmation popover.</td><td>not set (localized default)</td><td><code>"End this chat?"</code></td></tr><tr><td><code>sendBoxMicrophoneButtonColorOnListening</code></td><td>Microphone button color while actively listening.</td><td>not set (defaults to <code>#ff3333</code>)</td><td><code>"#605dec"</code></td></tr><tr><td><code>listeningOverlayBackgroundColor</code></td><td>Background of the speech "listening" overlay backdrop.</td><td>not set</td><td><code>"#000"</code></td></tr><tr><td><code>listeningOverlayBorderRadius</code></td><td>Corner rounding of the listening overlay.</td><td>not set</td><td><code>"10px"</code></td></tr><tr><td><code>listeningOverlayMargin</code></td><td>Outer margin of the listening overlay.</td><td>not set</td><td><code>"8px"</code></td></tr></tbody></table>

### Microsoft Theme Settings

These are the standard styling options built into [Bot Framework Web Chat](https://github.com/microsoft/BotFramework-WebChat) 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.&#x20;

For the full list of options from the Microsoft source, see [StyleOptions reference](https://github.com/microsoft/BotFramework-WebChat/blob/v4.18.0/packages/api/src/StyleOptions.ts).&#x20;

#### General & Layout

```jsonc
{
  "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"
  }
}
```

<table><thead><tr><th>Key</th><th width="345">Description</th><th width="109.5">Default</th><th>Example</th></tr></thead><tbody><tr><td><code>accent</code></td><td>Main accent color used across the chat.</td><td><code>"#605dec"</code></td><td><code>"#605dec"</code></td></tr><tr><td><code>backgroundColor</code></td><td>Transcript (chat) background color.</td><td><code>"White"</code></td><td><code>"White"</code></td></tr><tr><td><code>subtle</code></td><td>Color for secondary/faint text and icons.</td><td><code>"#909090"</code></td><td><code>"#909090"</code></td></tr><tr><td><code>paddingRegular</code></td><td>Standard padding inside components (px).</td><td><code>12</code></td><td><code>12</code></td></tr><tr><td><code>paddingWide</code></td><td>Wider padding, used for suggested-action buttons (px).</td><td><code>24</code></td><td><code>24</code></td></tr><tr><td><code>transitionDuration</code></td><td>Duration of visual transitions.</td><td><code>"0s"</code></td><td><code>"0.2s"</code></td></tr><tr><td><code>rootHeight</code></td><td>Height of the chat root container.</td><td><code>"100%"</code></td><td><code>"100%"</code></td></tr><tr><td><code>rootWidth</code></td><td>Width of the chat root container.</td><td><code>"100%"</code></td><td><code>"100%"</code></td></tr><tr><td><code>rootZIndex</code></td><td>Stacking order of the root container.</td><td><code>0</code></td><td><code>0</code></td></tr><tr><td><code>maxMessageLength</code></td><td>Most characters a visitor can type in one message.</td><td><code>2000</code></td><td><code>2000</code></td></tr><tr><td><code>messageActivityWordBreak</code></td><td>Word-break for message text: <code>normal</code>, <code>break-all</code>, <code>break-word</code>, <code>keep-all</code>.</td><td><code>"break-word"</code></td><td><code>"break-word"</code></td></tr></tbody></table>

#### Fonts & Markdown

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

<table><thead><tr><th width="190">Key</th><th width="354.5">Description</th><th>Default</th><th>Example</th></tr></thead><tbody><tr><td><code>fontSizeSmall</code></td><td>Size for secondary text (e.g. send status).</td><td><code>"80%"</code></td><td><code>"90%"</code></td></tr><tr><td><code>monospaceFont</code></td><td>Font for code blocks / error boxes.</td><td>Consolas stack</td><td><code>"Consolas"</code></td></tr><tr><td><code>primaryFont</code></td><td>Main font for the chat.</td><td>Calibri stack</td><td><code>"Arial"</code></td></tr><tr><td><code>markdownRespectCRLF</code></td><td>Preserve line breaks in formatted text.</td><td><code>true</code></td><td><code>true</code></td></tr><tr><td><code>markdownRenderHTML</code></td><td>Allow HTML inside Markdown messages.</td><td><code>true</code></td><td><code>true</code></td></tr><tr><td><code>markdownExternalLinkIconImage</code></td><td>Icon shown next to external links.</td><td>built-in icon</td><td><code>"url(…)"</code></td></tr></tbody></table>

#### Message Bubbles

```jsonc
{
  "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
  }
}
```

<table><thead><tr><th width="159.5">Key</th><th width="360">Description</th><th width="107">Default</th><th>Example</th></tr></thead><tbody><tr><td><code>bubbleBackground</code></td><td>Bot bubble background.</td><td><code>"#ECEFF1"</code></td><td><code>"#ECEFF1"</code></td></tr><tr><td><code>bubbleBorderColor</code></td><td>Bot bubble border color.</td><td><code>"#ECEFF1"</code></td><td><code>"#ECEFF1"</code></td></tr><tr><td><code>bubbleBorderRadius</code></td><td>Bot bubble corner radius. Declared <code>number</code>, but accepts a CSS length string (type-override).</td><td><code>"25px 25px 25px 0"</code></td><td><code>"30px 25px 25px 0"</code></td></tr><tr><td><code>bubbleBorderStyle</code></td><td>Bot bubble border style.</td><td><code>"solid"</code></td><td><code>"solid"</code></td></tr><tr><td><code>bubbleBorderWidth</code></td><td>Bot bubble border width.</td><td><code>0</code></td><td><code>1</code></td></tr><tr><td><code>bubbleTextColor</code></td><td>Bot bubble text color.</td><td><code>"#333"</code></td><td><code>"#333"</code></td></tr><tr><td><code>bubbleFromUserBackground</code></td><td>Visitor bubble background.</td><td><code>"#E8EAFD"</code></td><td><code>"#E8EAFD"</code></td></tr><tr><td><code>bubbleFromUserBorderColor</code></td><td>Visitor bubble border color.</td><td><code>"#E8EAFD"</code></td><td><code>"#E8EAFD"</code></td></tr><tr><td><code>bubbleFromUserBorderRadius</code></td><td>Visitor bubble corner radius. Declared <code>number</code>, but accepts a CSS length string (type-override).</td><td><code>"25px 25px 0 25px"</code></td><td><code>"30px 25px 0 25px"</code></td></tr><tr><td><code>bubbleFromUserBorderStyle</code></td><td>Visitor bubble border style.</td><td><code>"solid"</code></td><td><code>"solid"</code></td></tr><tr><td><code>bubbleFromUserBorderWidth</code></td><td>Visitor bubble border width.</td><td><code>0</code></td><td><code>1</code></td></tr><tr><td><code>bubbleFromUserTextColor</code></td><td>Visitor bubble text color.</td><td><code>"#0D1C8C"</code></td><td><code>"#0D1C8C"</code></td></tr><tr><td><code>bubbleFromUserNubOffset</code></td><td>Visitor bubble nub vertical offset (<code>top</code>/<code>bottom</code>/number).</td><td><code>"bottom"</code></td><td><code>0</code></td></tr><tr><td><code>bubbleFromUserNubSize</code></td><td>Visitor bubble nub size (0 = no nub).</td><td><code>0</code></td><td><code>10</code></td></tr><tr><td><code>bubbleNubOffset</code></td><td>Bot bubble nub vertical offset (<code>top</code>/<code>bottom</code>/number).</td><td><code>"bottom"</code></td><td><code>0</code></td></tr><tr><td><code>bubbleNubSize</code></td><td>Bot bubble nub size (0 = no nub).</td><td><code>0</code></td><td><code>10</code></td></tr><tr><td><code>bubbleImageHeight</code></td><td>Max height of images shown in bubbles (px).</td><td><code>240</code></td><td><code>240</code></td></tr><tr><td><code>bubbleMaxWidth</code></td><td>Maximum bubble width (px).</td><td><code>480</code></td><td><code>480</code></td></tr><tr><td><code>bubbleMinWidth</code></td><td>Minimum bubble width (px).</td><td><code>250</code></td><td><code>250</code></td></tr><tr><td><code>bubbleMinHeight</code></td><td>Minimum bubble height (px).</td><td><code>40</code></td><td><code>40</code></td></tr></tbody></table>

#### Avatars

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

<table><thead><tr><th width="185">Key</th><th width="322.5">Description</th><th width="120.5">Default</th><th>Example</th></tr></thead><tbody><tr><td><code>avatarSize</code></td><td>Height/width of avatars (px).</td><td><code>32</code></td><td><code>32</code></td></tr><tr><td><code>avatarBorderRadius</code></td><td>Avatar corner rounding (<code>50%</code> = circle).</td><td><code>"50%"</code></td><td><code>"50%"</code></td></tr><tr><td><code>showAvatarInGroup</code></td><td>Which messages show an avatar: <code>true</code>, <code>"sender"</code>, or <code>"status"</code>.</td><td><code>true</code></td><td><code>"sender"</code></td></tr><tr><td><code>botAvatarImage</code></td><td>Bot avatar image (URL).</td><td>built-in bot avatar</td><td><code>"https://…/bot.png"</code></td></tr><tr><td><code>botAvatarBackgroundColor</code></td><td>Bot avatar background.</td><td><code>"White"</code></td><td><code>"White"</code></td></tr><tr><td><code>botAvatarInitials</code></td><td>Letters shown when no bot image.</td><td><code>""</code></td><td><code>"SB"</code></td></tr><tr><td><code>userAvatarImage</code></td><td>Visitor avatar image (URL).</td><td>built-in user avatar</td><td><code>"https://…/user.png"</code></td></tr><tr><td><code>userAvatarBackgroundColor</code></td><td>Visitor avatar background.</td><td><code>"White"</code></td><td><code>"White"</code></td></tr><tr><td><code>userAvatarInitials</code></td><td>Letters shown when no visitor image.</td><td><code>""</code></td><td><code>"JD"</code></td></tr></tbody></table>

#### Send Box

```jsonc
{
  "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
  }
}
```

<table><thead><tr><th width="179">Key</th><th width="348">Description</th><th width="107.5">Default</th><th>Example</th></tr></thead><tbody><tr><td><code>hideSendBox</code></td><td>Hide the typing box entirely.</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>hideUploadButton</code></td><td>Hide the file-upload button.</td><td><code>true</code></td><td><code>false</code></td></tr><tr><td><code>hideTelephoneKeypadButton</code></td><td>Hide the telephone-keypad button.</td><td><code>true</code></td><td><code>false</code></td></tr><tr><td><code>sendBoxBackground</code></td><td>Send box background color.</td><td><code>"White"</code></td><td><code>"White"</code></td></tr><tr><td><code>sendBoxTextColor</code></td><td>Text color while typing.</td><td><code>"#333"</code></td><td><code>"#333"</code></td></tr><tr><td><code>sendBoxHeight</code></td><td>Send box height (px).</td><td><code>52</code></td><td><code>52</code></td></tr><tr><td><code>sendBoxMaxHeight</code></td><td>Send box maximum height (px).</td><td><code>200</code></td><td><code>200</code></td></tr><tr><td><code>sendBoxTextWrap</code></td><td>Allow the input text to wrap onto new lines.</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>sendBoxPlaceholderColor</code></td><td>Color of the placeholder hint.</td><td>not set (uses <code>subtle</code>)</td><td><code>"#999"</code></td></tr><tr><td><code>sendBoxDisabledTextColor</code></td><td>Text color when typing is locked.</td><td>not set (uses <code>subtle</code>)</td><td><code>"#CCC"</code></td></tr><tr><td><code>sendBoxBorderTop</code></td><td>Send box top border.</td><td><code>"solid 1px #E6E6E6"</code></td><td><code>"solid 1px #E6E6E6"</code></td></tr><tr><td><code>sendBoxBorderBottom</code></td><td>Send box bottom border.</td><td><code>""</code></td><td><code>"solid 1px #E6E6E6"</code></td></tr><tr><td><code>sendBoxBorderLeft</code></td><td>Send box left border.</td><td><code>""</code></td><td><code>""</code></td></tr><tr><td><code>sendBoxBorderRight</code></td><td>Send box right border.</td><td><code>""</code></td><td><code>""</code></td></tr><tr><td><code>sendBoxButtonColor</code></td><td>Send box button icon color.</td><td>not set (uses <code>subtle</code>)</td><td><code>"#605dec"</code></td></tr><tr><td><code>sendBoxButtonColorOnHover</code></td><td>Button icon color on hover.</td><td><code>"#333"</code></td><td><code>"#333"</code></td></tr><tr><td><code>sendBoxButtonColorOnFocus</code></td><td>Button icon color on focus.</td><td><code>"#333"</code></td><td><code>"#333"</code></td></tr><tr><td><code>sendBoxButtonColorOnActive</code></td><td>Button icon color while active.</td><td>not set</td><td><code>"#333"</code></td></tr><tr><td><code>sendBoxButtonColorOnDisabled</code></td><td>Button icon color when disabled.</td><td><code>"#CCC"</code></td><td><code>"#A19F9D"</code></td></tr><tr><td><code>sendBoxButtonShadeColor</code></td><td>Background shade behind a send box button.</td><td><code>"transparent"</code></td><td><code>"transparent"</code></td></tr><tr><td><code>sendBoxButtonShadeColorOnHover</code></td><td>Shade on hover.</td><td><code>"transparent"</code></td><td><code>"#F3F2F1"</code></td></tr><tr><td><code>sendBoxButtonShadeColorOnFocus</code></td><td>Shade on focus.</td><td><code>"transparent"</code></td><td><code>"transparent"</code></td></tr><tr><td><code>sendBoxButtonShadeColorOnActive</code></td><td>Shade while active.</td><td><code>"transparent"</code></td><td><code>"#EDEBE9"</code></td></tr><tr><td><code>sendBoxButtonShadeColorOnDisabled</code></td><td>Shade when disabled.</td><td><code>"transparent"</code></td><td><code>"#F3F2F1"</code></td></tr><tr><td><code>sendBoxButtonShadeBorderRadius</code></td><td>Corner rounding of the button shade.</td><td><code>2</code></td><td><code>2</code></td></tr><tr><td><code>sendBoxButtonShadeInset</code></td><td>Inset of the button shade.</td><td><code>2</code></td><td><code>2</code></td></tr><tr><td><code>sendBoxButtonAlignment</code></td><td>Vertical alignment of send box buttons: <code>stretch</code>, <code>top</code>, <code>bottom</code>.</td><td><code>"stretch"</code></td><td><code>"stretch"</code></td></tr><tr><td><code>microphoneButtonColorOnDictate</code></td><td>Microphone color while recording.</td><td><code>"#F33"</code></td><td><code>"#F33"</code></td></tr><tr><td><code>showSpokenText</code></td><td>Visually show spoken text.</td><td><code>true</code></td><td><code>true</code></td></tr><tr><td><code>sendAttachmentOn</code></td><td>When files are sent: <code>attach</code> (immediately) or <code>send</code>.</td><td><code>"attach"</code></td><td><code>"attach"</code></td></tr><tr><td><code>uploadAccept</code></td><td>Which file types the upload button accepts.</td><td>not set</td><td><code>"image/*"</code></td></tr><tr><td><code>uploadMultiple</code></td><td>Allow selecting several files at once.</td><td><code>true</code></td><td><code>true</code></td></tr></tbody></table>

#### Suggested Action Buttons

```jsonc
{
  "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
  }
}
```

<table><thead><tr><th width="160">Key</th><th width="379.5">Description</th><th width="114.5">Default</th><th>Example</th></tr></thead><tbody><tr><td><code>suggestedActionLayout</code></td><td>Layout: <code>carousel</code>, <code>flow</code>, or <code>stacked</code>.</td><td><code>"carousel"</code></td><td><code>"stacked"</code></td></tr><tr><td><code>suggestedActionBackgroundColor</code></td><td>Button background.</td><td><code>"White"</code></td><td><code>"White"</code></td></tr><tr><td><code>suggestedActionTextColor</code></td><td>Button text color.</td><td>not set (uses <code>accent</code>)</td><td><code>"#605dec"</code></td></tr><tr><td><code>suggestedActionBorderColor</code></td><td>Button border color.</td><td>not set (uses <code>accent</code>)</td><td><code>"#605dec"</code></td></tr><tr><td><code>suggestedActionBorderStyle</code></td><td>Button border style.</td><td><code>"solid"</code></td><td><code>"solid"</code></td></tr><tr><td><code>suggestedActionBorderWidth</code></td><td>Button border width.</td><td><code>2</code></td><td><code>2</code></td></tr><tr><td><code>suggestedActionBorderRadius</code></td><td>Button corner rounding.</td><td><code>"6px"</code></td><td><code>"6px"</code></td></tr><tr><td><code>suggestedActionHeight</code></td><td>Button height (px).</td><td><code>40</code></td><td><code>40</code></td></tr><tr><td><code>suggestedActionImageHeight</code></td><td>Image height inside buttons (px).</td><td><code>20</code></td><td><code>20</code></td></tr><tr><td><code>suggestedActionBackgroundColorOnHover</code></td><td>Background on hover.</td><td><code>"White"</code></td><td><code>"White"</code></td></tr><tr><td><code>suggestedActionBackgroundColorOnFocus</code></td><td>Background on focus.</td><td><code>"White"</code></td><td><code>"White"</code></td></tr><tr><td><code>suggestedActionBackgroundColorOnActive</code></td><td>Background while active.</td><td><code>"White"</code></td><td><code>"White"</code></td></tr><tr><td><code>suggestedActionBackgroundColorOnDisabled</code></td><td>Background when disabled.</td><td>not set</td><td><code>"#EEE"</code></td></tr><tr><td><code>suggestedActionTextColorOnHover</code> / <code>OnFocus</code> / <code>OnActive</code></td><td>Text color per state.</td><td>not set</td><td><code>"#333"</code></td></tr><tr><td><code>suggestedActionTextColorOnDisabled</code></td><td>Text color when disabled.</td><td>not set (uses <code>subtle</code>)</td><td><code>"#999"</code></td></tr><tr><td><code>suggestedActionBorderColorOnDisabled</code></td><td>Border color when disabled.</td><td><code>"#E6E6E6"</code></td><td><code>"#E6E6E6"</code></td></tr><tr><td><code>suggestedActionBorderStyleOnDisabled</code></td><td>Border style when disabled.</td><td><code>"solid"</code></td><td><code>"solid"</code></td></tr><tr><td><code>suggestedActionBorderWidthOnDisabled</code></td><td>Border width when disabled.</td><td><code>2</code></td><td><code>2</code></td></tr><tr><td><code>suggestedActionBorderColorOnHover</code> / <code>OnFocus</code> / <code>OnActive</code></td><td>Border color per state.</td><td>not set</td><td><code>"#605dec"</code></td></tr><tr><td><code>suggestedActionBorderStyleOnHover</code> / <code>OnFocus</code> / <code>OnActive</code></td><td>Border style per state.</td><td>not set</td><td><code>"solid"</code></td></tr><tr><td><code>suggestedActionBorderWidthOnHover</code> / <code>OnFocus</code> / <code>OnActive</code></td><td>Border width per state.</td><td>not set</td><td><code>2</code></td></tr><tr><td><code>suggestedActionsCarouselFlipperBoxWidth</code></td><td>Carousel scroll-arrow bounding box (px).</td><td><code>40</code></td><td><code>40</code></td></tr><tr><td><code>suggestedActionsCarouselFlipperSize</code></td><td>Carousel scroll-arrow visible size (px).</td><td><code>20</code></td><td><code>20</code></td></tr><tr><td><code>suggestedActionsCarouselFlipperCursor</code></td><td>Cursor over the carousel arrows.</td><td>not set</td><td><code>"pointer"</code></td></tr><tr><td><code>suggestedActionsFlowMaxHeight</code></td><td>Max height of the button area in <code>flow</code> layout. Declared <code>undefined</code>, but accepts a <strong>number</strong> (type-override).</td><td><code>240</code></td><td><code>240</code></td></tr><tr><td><code>suggestedActionsStackedHeight</code></td><td>Max height of the button area in <code>stacked</code> layout.</td><td><code>240</code></td><td><code>240</code></td></tr><tr><td><code>suggestedActionsStackedOverflow</code></td><td>Stacked overflow: <code>auto</code>, <code>hidden</code>, <code>scroll</code>, <code>visible</code>.</td><td>not set</td><td><code>"auto"</code></td></tr><tr><td><code>suggestedActionsStackedLayoutButtonMaxHeight</code></td><td>Max height of a single stacked button.</td><td>not set</td><td><code>"100%"</code></td></tr><tr><td><code>suggestedActionsStackedLayoutButtonTextWrap</code></td><td>Allow long button text to wrap (stacked only).</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>suggestedActionBackground</code></td><td><strong>(DEPRECATED)</strong> Use <code>suggestedActionBackgroundColor</code>.</td><td>not set</td><td>—</td></tr><tr><td><code>suggestedActionActiveBackground</code></td><td><strong>(DEPRECATED)</strong> Use <code>suggestedActionBackgroundColorOnActive</code>.</td><td>not set</td><td>—</td></tr><tr><td><code>suggestedActionFocusBackground</code></td><td><strong>(DEPRECATED)</strong> Use <code>suggestedActionBackgroundColorOnFocus</code>.</td><td>not set</td><td>—</td></tr><tr><td><code>suggestedActionHoverBackground</code></td><td><strong>(DEPRECATED)</strong> Use <code>suggestedActionBackgroundColorOnHover</code>.</td><td>not set</td><td>—</td></tr><tr><td><code>suggestedActionDisabledBackground</code></td><td><strong>(DEPRECATED)</strong> Use <code>suggestedActionBackgroundColorOnDisabled</code>.</td><td>not set</td><td>—</td></tr><tr><td><code>suggestedActionDisabledBorderColor</code></td><td><strong>(DEPRECATED)</strong> Use <code>suggestedActionBorderColorOnDisabled</code>.</td><td>not set</td><td>—</td></tr><tr><td><code>suggestedActionDisabledBorderStyle</code></td><td><strong>(DEPRECATED)</strong> Use <code>suggestedActionBorderStyleOnDisabled</code>.</td><td>not set</td><td>—</td></tr><tr><td><code>suggestedActionDisabledBorderWidth</code></td><td><strong>(DEPRECATED)</strong> Use <code>suggestedActionBorderWidthOnDisabled</code>.</td><td>not set</td><td>—</td></tr><tr><td><code>suggestedActionDisabledTextColor</code></td><td><strong>(DEPRECATED)</strong> Use <code>suggestedActionTextColorOnDisabled</code>.</td><td>not set</td><td>—</td></tr></tbody></table>

#### Timestamps

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

<table><thead><tr><th width="156.5">Key</th><th width="372">Description</th><th width="129">Default</th><th>Example</th></tr></thead><tbody><tr><td><code>groupTimestamp</code></td><td>Group messages under one timestamp: <code>true</code>/<code>false</code>/number (ms window).</td><td><code>true</code></td><td><code>300000</code></td></tr><tr><td><code>timestampFormat</code></td><td>Time display: <code>relative</code> or <code>absolute</code>.</td><td><code>"relative"</code></td><td><code>"relative"</code></td></tr><tr><td><code>timestampColor</code></td><td>Timestamp text color.</td><td>not set (uses <code>subtle</code>)</td><td><code>"#999"</code></td></tr><tr><td><code>sendTimeout</code></td><td>Time (ms) before a message is marked failed.</td><td><code>20000</code></td><td><code>20000</code></td></tr><tr><td><code>sendTimeoutForAttachments</code></td><td>Same, for file attachments (ms).</td><td><code>120000</code></td><td><code>120000</code></td></tr></tbody></table>

#### Toasts & Notifications

```jsonc
{
  "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"
  }
}
```

<table><thead><tr><th width="164">Key</th><th width="351">Description</th><th width="109">Default</th><th>Example</th></tr></thead><tbody><tr><td><code>hideToaster</code></td><td>Hide all toast banners.</td><td><code>true</code></td><td><code>false</code></td></tr><tr><td><code>notificationDebounceTimeout</code></td><td>Delay (ms) to avoid flickering notifications.</td><td><code>400</code></td><td><code>400</code></td></tr><tr><td><code>notificationText</code></td><td>Color of small notification text.</td><td><code>"#5E5E5E"</code></td><td><code>"#5E5E5E"</code></td></tr><tr><td><code>toasterHeight</code></td><td>Toaster height (px).</td><td><code>32</code></td><td><code>32</code></td></tr><tr><td><code>toasterMaxHeight</code></td><td>Toaster max height (px).</td><td><code>160</code></td><td><code>160</code></td></tr><tr><td><code>toasterSingularMaxHeight</code></td><td>Single-toast max height (px).</td><td><code>50</code></td><td><code>50</code></td></tr><tr><td><code>toastFontSize</code></td><td>Toast text size.</td><td><code>"87.5%"</code></td><td><code>"87.5%"</code></td></tr><tr><td><code>toastIconWidth</code></td><td>Toast icon width (px).</td><td><code>36</code></td><td><code>36</code></td></tr><tr><td><code>toastTextPadding</code></td><td>Toast text padding (px).</td><td><code>6</code></td><td><code>6</code></td></tr><tr><td><code>toastSeparatorColor</code></td><td>Toast separator color.</td><td><code>"#E8EAEC"</code></td><td><code>"#E8EAEC"</code></td></tr><tr><td><code>toastInfoBackgroundColor</code> / <code>toastInfoColor</code></td><td>Info toast background / text.</td><td><code>"#605dec"</code> / <code>"white"</code></td><td><code>"#605dec"</code> / <code>"white"</code></td></tr><tr><td><code>toastSuccessBackgroundColor</code> / <code>toastSuccessColor</code></td><td>Success toast background / text.</td><td><code>"#DFF6DD"</code> / <code>"#107C10"</code></td><td>—</td></tr><tr><td><code>toastWarnBackgroundColor</code> / <code>toastWarnColor</code></td><td>Warning toast background / text.</td><td><code>"#FFF4CE"</code> / <code>"#3B3A39"</code></td><td>—</td></tr><tr><td><code>toastErrorBackgroundColor</code> / <code>toastErrorColor</code></td><td>Error toast background / text.</td><td><code>"#FDE7E9"</code> / <code>"#A80000"</code></td><td>—</td></tr></tbody></table>

#### Connectivity

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

<table><thead><tr><th width="181.5">Key</th><th width="321.5">Description</th><th width="109">Default</th><th>Example</th></tr></thead><tbody><tr><td><code>slowConnectivity</code></td><td>Color for the "slow connection" status.</td><td><code>"#EAA300"</code></td><td><code>"#EAA300"</code></td></tr><tr><td><code>failedConnectivity</code></td><td>Color for the "connection failed" status.</td><td><code>"#C50F1F"</code></td><td><code>"#C50F1F"</code></td></tr><tr><td><code>slowConnectionAfter</code></td><td>Wait (ms) before showing "slow".</td><td><code>15000</code></td><td><code>15000</code></td></tr><tr><td><code>connectivityTextSize</code></td><td>Status text size.</td><td><code>"75%"</code></td><td><code>"75%"</code></td></tr><tr><td><code>connectivityIconPadding</code></td><td>Padding around the status icon (px).</td><td><code>14.4</code></td><td><code>14.4</code></td></tr><tr><td><code>connectivityMarginLeftRight</code></td><td>Left/right margin of the status (px).</td><td><code>16.8</code></td><td><code>16.8</code></td></tr><tr><td><code>connectivityMarginTopBottom</code></td><td>Top/bottom margin of the status (px).</td><td><code>9.6</code></td><td><code>9.6</code></td></tr></tbody></table>

#### Scroll-To-End Button

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

<table><thead><tr><th width="177">Key</th><th width="378.5">Description</th><th width="102">Default</th><th>Example</th></tr></thead><tbody><tr><td><code>scrollToEndButtonBehavior</code></td><td>When it shows: <code>unread</code>, <code>any</code>, or <code>false</code> (never).</td><td><code>"unread"</code></td><td><code>"unread"</code></td></tr><tr><td><code>scrollToEndButtonFontSize</code></td><td>Button text size.</td><td><code>16</code></td><td><code>16</code></td></tr><tr><td><code>autoScrollSnapOnActivity</code></td><td>Pause auto-scroll after N activities (<code>true</code>/<code>false</code>/number).</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>autoScrollSnapOnActivityOffset</code></td><td>Over/underscroll (px) after activity snap.</td><td><code>0</code></td><td><code>0</code></td></tr><tr><td><code>autoScrollSnapOnPage</code></td><td>Pause auto-scroll after page fill (<code>true</code>/<code>false</code>/fraction).</td><td><code>false</code></td><td><code>true</code></td></tr><tr><td><code>autoScrollSnapOnPageOffset</code></td><td>Over/underscroll (px) after page snap.</td><td><code>0</code></td><td><code>0</code></td></tr><tr><td><code>newMessagesButtonFontSize</code></td><td><strong>(DEPRECATED)</strong> Renamed to <code>scrollToEndButtonFontSize</code>.</td><td>not set</td><td>—</td></tr></tbody></table>

#### Typing & Loading Animations

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

<table><thead><tr><th width="179.5">Key</th><th width="378.5">Description</th><th>Default</th><th>Example</th></tr></thead><tbody><tr><td><code>typingAnimationDuration</code></td><td>How long the "typing…" animation shows (ms).</td><td><code>5000</code></td><td><code>5000</code></td></tr><tr><td><code>typingAnimationHeight</code></td><td>Typing animation height (px).</td><td><code>35</code></td><td><code>35</code></td></tr><tr><td><code>typingAnimationWidth</code></td><td>Typing animation width (px).</td><td><code>53</code></td><td><code>53</code></td></tr><tr><td><code>typingAnimationBackgroundImage</code></td><td>Custom image for the typing animation.</td><td>built-in animation</td><td><code>"url(…)"</code></td></tr><tr><td><code>spinnerAnimationHeight</code></td><td>Loading spinner height (px).</td><td><code>16</code></td><td><code>16</code></td></tr><tr><td><code>spinnerAnimationWidth</code></td><td>Loading spinner width (px).</td><td><code>16</code></td><td><code>16</code></td></tr><tr><td><code>spinnerAnimationPadding</code></td><td>Loading spinner padding (px).</td><td><code>12</code></td><td><code>12</code></td></tr><tr><td><code>spinnerAnimationBackgroundImage</code></td><td>Custom image for the loading spinner.</td><td>not set</td><td><code>"url(…)"</code></td></tr></tbody></table>

#### Uploads & Video

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

<table><thead><tr><th width="208.5">Key</th><th width="358.5">Description</th><th width="100.5">Default</th><th>Example</th></tr></thead><tbody><tr><td><code>enableUploadThumbnail</code></td><td>Create a small preview for uploaded images.</td><td><code>true</code></td><td><code>true</code></td></tr><tr><td><code>uploadThumbnailWidth</code></td><td>Preview width (px).</td><td><code>720</code></td><td><code>720</code></td></tr><tr><td><code>uploadThumbnailHeight</code></td><td>Preview height (px).</td><td><code>360</code></td><td><code>360</code></td></tr><tr><td><code>uploadThumbnailQuality</code></td><td>Preview image quality (0–1).</td><td><code>0.6</code></td><td><code>0.6</code></td></tr><tr><td><code>uploadThumbnailContentType</code></td><td>Preview image format.</td><td><code>"image/jpeg"</code></td><td><code>"image/jpeg"</code></td></tr><tr><td><code>videoHeight</code></td><td>Height of videos shown in chat (px).</td><td><code>270</code></td><td><code>270</code></td></tr></tbody></table>

#### Transcript & Overlay Buttons

```jsonc
{
  "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
  }
}
```

<table><thead><tr><th width="194">Key</th><th width="277">Description</th><th width="132">Default</th><th>Example</th></tr></thead><tbody><tr><td><code>transcriptOverlayButtonBackground</code></td><td>Background of overlay buttons (e.g. save image).</td><td><code>"rgba(0, 0, 0, .6)"</code></td><td><code>"rgba(0,0,0,.6)"</code></td></tr><tr><td><code>transcriptOverlayButtonBackgroundOnHover</code></td><td>Overlay button background on hover.</td><td><code>"rgba(0, 0, 0, .8)"</code></td><td>—</td></tr><tr><td><code>transcriptOverlayButtonBackgroundOnFocus</code></td><td>Overlay button background on focus.</td><td><code>"rgba(0, 0, 0, .8)"</code></td><td>—</td></tr><tr><td><code>transcriptOverlayButtonBackgroundOnDisabled</code></td><td>Overlay button background when disabled.</td><td><code>"rgba(0, 0, 0, .6)"</code></td><td>—</td></tr><tr><td><code>transcriptOverlayButtonColor</code></td><td>Overlay button icon/text color.</td><td><code>"White"</code></td><td><code>"White"</code></td></tr><tr><td><code>transcriptOverlayButtonColorOnDisabled</code></td><td>Overlay button color when disabled.</td><td><code>"White"</code></td><td>—</td></tr><tr><td><code>transcriptOverlayButtonColorOnHover</code> / <code>OnFocus</code></td><td>Overlay button color on hover/focus.</td><td>not set (uses base color)</td><td>—</td></tr><tr><td><code>transcriptTerminatorBackgroundColor</code></td><td>Background of the "live chat ended" divider.</td><td><code>"#595959"</code></td><td><code>"#595959"</code></td></tr><tr><td><code>transcriptTerminatorColor</code></td><td>Text color of that divider.</td><td><code>"White"</code></td><td><code>"White"</code></td></tr><tr><td><code>transcriptTerminatorFontSize</code></td><td>Text size of that divider (px).</td><td><code>12</code></td><td><code>12</code></td></tr><tr><td><code>transcriptTerminatorBorderRadius</code></td><td>Corner rounding of that divider.</td><td><code>5</code></td><td><code>5</code></td></tr></tbody></table>

#### Emoji

```jsonc
{
  "styleSetOptions": {
    "emojiSet": true
  }
}
```

<table><thead><tr><th width="116.5">Key</th><th width="344">Description</th><th>Default</th><th>Example</th></tr></thead><tbody><tr><td><code>emojiSet</code></td><td>Enable the built-in emoji set (<code>true</code>) or supply a custom emoticon→emoji map.</td><td><code>true</code></td><td><code>true</code></td></tr></tbody></table>

#### Accessibility & Keyboard Focus

Rarely changed. They style focus outlines during keyboard navigation.

```jsonc
{
  "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
  }
}
```

<table><thead><tr><th width="181">Key</th><th width="371.5">Description</th><th width="110.5">Default</th><th>Example</th></tr></thead><tbody><tr><td><code>internalLiveRegionFadeAfter</code></td><td>How long (ms) screen-reader announcements stay before fading.</td><td><code>1000</code></td><td><code>1000</code></td></tr><tr><td><code>sendBoxButtonKeyboardFocusIndicatorBorderColor</code></td><td>Focus outline color on send box buttons.</td><td><code>"#605E5C"</code></td><td><code>"#605E5C"</code></td></tr><tr><td><code>sendBoxButtonKeyboardFocusIndicatorBorderStyle</code></td><td>Focus outline style on send box buttons.</td><td><code>"solid"</code></td><td><code>"solid"</code></td></tr><tr><td><code>sendBoxButtonKeyboardFocusIndicatorBorderWidth</code></td><td>Focus outline width on send box buttons.</td><td><code>1</code></td><td><code>1</code></td></tr><tr><td><code>sendBoxButtonKeyboardFocusIndicatorBorderRadius</code></td><td>Focus outline radius on send box buttons.</td><td><code>0</code></td><td><code>0</code></td></tr><tr><td><code>sendBoxButtonKeyboardFocusIndicatorInset</code></td><td>Focus outline inset on send box buttons.</td><td><code>4</code></td><td><code>4</code></td></tr><tr><td><code>suggestedActionKeyboardFocusIndicatorBorderColor</code></td><td>Focus outline color on suggested actions.</td><td><code>"#605E5C"</code></td><td><code>"#605E5C"</code></td></tr><tr><td><code>suggestedActionKeyboardFocusIndicatorBorderStyle</code></td><td>Focus outline style on suggested actions.</td><td><code>"dashed"</code></td><td><code>"dashed"</code></td></tr><tr><td><code>suggestedActionKeyboardFocusIndicatorBorderWidth</code></td><td>Focus outline width on suggested actions.</td><td><code>1</code></td><td><code>1</code></td></tr><tr><td><code>suggestedActionKeyboardFocusIndicatorBorderRadius</code></td><td>Focus outline radius on suggested actions.</td><td><code>0</code></td><td><code>0</code></td></tr><tr><td><code>suggestedActionKeyboardFocusIndicatorInset</code></td><td>Focus outline inset on suggested actions.</td><td><code>2</code></td><td><code>2</code></td></tr><tr><td><code>suggestedActionsVisualKeyboardIndicatorColor</code></td><td>Outline color on a focused suggested action.</td><td><code>"Black"</code></td><td><code>"Black"</code></td></tr><tr><td><code>suggestedActionsVisualKeyboardIndicatorStyle</code></td><td>Outline style on a focused suggested action.</td><td><code>"solid"</code></td><td><code>"solid"</code></td></tr><tr><td><code>suggestedActionsVisualKeyboardIndicatorWidth</code></td><td>Outline width on a focused suggested action.</td><td><code>2</code></td><td><code>2</code></td></tr><tr><td><code>transcriptVisualKeyboardIndicatorColor</code></td><td>Outline color around the focused transcript.</td><td><code>"Black"</code></td><td><code>"Black"</code></td></tr><tr><td><code>transcriptVisualKeyboardIndicatorStyle</code></td><td>Outline style around the focused transcript.</td><td><code>"solid"</code></td><td><code>"solid"</code></td></tr><tr><td><code>transcriptVisualKeyboardIndicatorWidth</code></td><td>Outline width around the focused transcript.</td><td><code>0</code></td><td><code>0</code></td></tr><tr><td><code>transcriptActivityVisualKeyboardIndicatorColor</code></td><td>Outline color around a focused message.</td><td><code>"#909090"</code></td><td><code>"#909090"</code></td></tr><tr><td><code>transcriptActivityVisualKeyboardIndicatorStyle</code></td><td>Outline style around a focused message.</td><td><code>"dashed"</code></td><td><code>"dashed"</code></td></tr><tr><td><code>transcriptActivityVisualKeyboardIndicatorWidth</code></td><td>Outline width around a focused message.</td><td><code>0</code></td><td><code>0</code></td></tr></tbody></table>

{% hint style="success" %}
You can now configure any part of the Webchat widget through Custom Settings, from connection and behavior to its full visual theme.
{% endhint %}