> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Widgets

API operations for widgets. Browse the routes below for parameters, request examples, and responses.

API version: Selected per operation

## Get widget

Returns the widget configuration stored on the environment's draft version: which surface the embed runs and the settings of each surface. Visitors see the published version, so this can differ from the live site until the environment is published.

### Endpoint

```http
GET /v1/stable/widget
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Responses

#### 200

Returns the widget with its surface `type` and its `chat`, `voice`, `common`, and `security` blocks, as stored on the environment's draft version.

Schema:

```json
{
  "$ref": "#/components/schemas/StableWidgetResponse"
}
```

Example:

```json
{
  "widget": {
    "type": "<WidgetSettingsWidgetType>",
    "chat": "<WidgetSettingsChatSettings>",
    "voice": "<WidgetSettingsVoiceSettings>",
    "common": "<WidgetSettingsCommonSettings>",
    "security": "<WidgetSettingsSecuritySettings>"
  }
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v1/stable/widget?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/widget?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/widget?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf widget get --project-id <projectID> --environment-alias <environmentAlias>
```


## Update widget

Changes the widget configuration on the environment's draft version, such as its surface, colors, launcher, disclaimers, or approved domains. The change reaches visitors once the environment is published.

### Endpoint

```http
PATCH /v1/stable/widget
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/StableWidgetUpdateRequest"
          }
        ]
      }
    }
  }
}
```

### Responses

#### 200

Confirms the widget configuration was updated on the draft version. The body is a message only, so read the widget back to see the settings as they now stand.

Schema:

```json
{
  "$ref": "#/components/schemas/StableUpdateResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request PATCH \
  --url 'https://realtime-api.voiceflow.com/v1/stable/widget?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "chat",
  "chat": {
    "renderMode": "<WidgetSettingsChatRenderMode>",
    "headerImage": "<WidgetSettingsChatSettingsHeaderImage>",
    "agentImage": "<WidgetSettingsChatSettingsAgentImage>",
    "banner": "<WidgetSettingsChatSettingsBanner>",
    "placeholderText": "<string>",
    "disclaimer": "<WidgetSettingsChatDisclaimer>",
    "aiDisclaimer": "<WidgetSettingsChatSettingsAIDisclaimer>",
    "handoffToAgentImageURL": "<string>",
    "streamingDisabled": true,
    "responseLoader": "<WidgetSettingsChatSettingsResponseLoader>",
    "voiceInput": true,
    "voiceOutput": true,
    "voiceOutputMuted": true,
    "voiceMode": true,
    "notificationSound": true,
    "fileUpload": "<WidgetSettingsChatSettingsFileUpload>",
    "csat": "<WidgetSettingsChatSettingsCSAT>"
  },
  "voice": {
    "renderMode": "<WidgetSettingsVoiceRenderMode>",
    "content": "<WidgetSettingsVoiceSettingsContent>"
  },
  "common": {
    "sideSpacing": "<string>",
    "bottomSpacing": "<string>",
    "width": "<string>",
    "position": "<WidgetSettingsWidgetPosition>",
    "fontFamily": "<string>",
    "primaryColor": {
      "color": "<string>",
      "palette": "<WidgetSettingsColorPalette>"
    },
    "poweredBy": true,
    "launcher": "<WidgetSettingsCommonSettingsLauncher>",
    "footerLink": "<WidgetSettingsCommonSettingsFooterLink>",
    "persistence": "<WidgetSettingsChatPersistence>",
    "featureFlags": "<WidgetSettingsCommonSettingsFeatureFlags>"
  },
  "security": {
    "approvedDomains": "<WidgetSettingsSecuritySettingsApprovedDomains>",
    "disableTranscript": true,
    "isTranscriptDownloadEnabled": true
  }
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/widget?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "type": "chat",
    "chat": {
      "renderMode": "<WidgetSettingsChatRenderMode>",
      "headerImage": "<WidgetSettingsChatSettingsHeaderImage>",
      "agentImage": "<WidgetSettingsChatSettingsAgentImage>",
      "banner": "<WidgetSettingsChatSettingsBanner>",
      "placeholderText": "<string>",
      "disclaimer": "<WidgetSettingsChatDisclaimer>",
      "aiDisclaimer": "<WidgetSettingsChatSettingsAIDisclaimer>",
      "handoffToAgentImageURL": "<string>",
      "streamingDisabled": true,
      "responseLoader": "<WidgetSettingsChatSettingsResponseLoader>",
      "voiceInput": true,
      "voiceOutput": true,
      "voiceOutputMuted": true,
      "voiceMode": true,
      "notificationSound": true,
      "fileUpload": "<WidgetSettingsChatSettingsFileUpload>",
      "csat": "<WidgetSettingsChatSettingsCSAT>"
    },
    "voice": {
      "renderMode": "<WidgetSettingsVoiceRenderMode>",
      "content": "<WidgetSettingsVoiceSettingsContent>"
    },
    "common": {
      "sideSpacing": "<string>",
      "bottomSpacing": "<string>",
      "width": "<string>",
      "position": "<WidgetSettingsWidgetPosition>",
      "fontFamily": "<string>",
      "primaryColor": {
        "color": "<string>",
        "palette": "<WidgetSettingsColorPalette>"
      },
      "poweredBy": true,
      "launcher": "<WidgetSettingsCommonSettingsLauncher>",
      "footerLink": "<WidgetSettingsCommonSettingsFooterLink>",
      "persistence": "<WidgetSettingsChatPersistence>",
      "featureFlags": "<WidgetSettingsCommonSettingsFeatureFlags>"
    },
    "security": {
      "approvedDomains": "<WidgetSettingsSecuritySettingsApprovedDomains>",
      "disableTranscript": true,
      "isTranscriptDownloadEnabled": true
    }
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.patch(
    'https://realtime-api.voiceflow.com/v1/stable/widget?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "type": "chat",
      "chat": {
        "renderMode": "<WidgetSettingsChatRenderMode>",
        "headerImage": "<WidgetSettingsChatSettingsHeaderImage>",
        "agentImage": "<WidgetSettingsChatSettingsAgentImage>",
        "banner": "<WidgetSettingsChatSettingsBanner>",
        "placeholderText": "<string>",
        "disclaimer": "<WidgetSettingsChatDisclaimer>",
        "aiDisclaimer": "<WidgetSettingsChatSettingsAIDisclaimer>",
        "handoffToAgentImageURL": "<string>",
        "streamingDisabled": True,
        "responseLoader": "<WidgetSettingsChatSettingsResponseLoader>",
        "voiceInput": True,
        "voiceOutput": True,
        "voiceOutputMuted": True,
        "voiceMode": True,
        "notificationSound": True,
        "fileUpload": "<WidgetSettingsChatSettingsFileUpload>",
        "csat": "<WidgetSettingsChatSettingsCSAT>"
      },
      "voice": {
        "renderMode": "<WidgetSettingsVoiceRenderMode>",
        "content": "<WidgetSettingsVoiceSettingsContent>"
      },
      "common": {
        "sideSpacing": "<string>",
        "bottomSpacing": "<string>",
        "width": "<string>",
        "position": "<WidgetSettingsWidgetPosition>",
        "fontFamily": "<string>",
        "primaryColor": {
          "color": "<string>",
          "palette": "<WidgetSettingsColorPalette>"
        },
        "poweredBy": True,
        "launcher": "<WidgetSettingsCommonSettingsLauncher>",
        "footerLink": "<WidgetSettingsCommonSettingsFooterLink>",
        "persistence": "<WidgetSettingsChatPersistence>",
        "featureFlags": "<WidgetSettingsCommonSettingsFeatureFlags>"
      },
      "security": {
        "approvedDomains": "<WidgetSettingsSecuritySettingsApprovedDomains>",
        "disableTranscript": True,
        "isTranscriptDownloadEnabled": True
      }
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf widget update --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "type": "chat",
  "chat": {
    "renderMode": "<WidgetSettingsChatRenderMode>",
    "headerImage": "<WidgetSettingsChatSettingsHeaderImage>",
    "agentImage": "<WidgetSettingsChatSettingsAgentImage>",
    "banner": "<WidgetSettingsChatSettingsBanner>",
    "placeholderText": "<string>",
    "disclaimer": "<WidgetSettingsChatDisclaimer>",
    "aiDisclaimer": "<WidgetSettingsChatSettingsAIDisclaimer>",
    "handoffToAgentImageURL": "<string>",
    "streamingDisabled": true,
    "responseLoader": "<WidgetSettingsChatSettingsResponseLoader>",
    "voiceInput": true,
    "voiceOutput": true,
    "voiceOutputMuted": true,
    "voiceMode": true,
    "notificationSound": true,
    "fileUpload": "<WidgetSettingsChatSettingsFileUpload>",
    "csat": "<WidgetSettingsChatSettingsCSAT>"
  },
  "voice": {
    "renderMode": "<WidgetSettingsVoiceRenderMode>",
    "content": "<WidgetSettingsVoiceSettingsContent>"
  },
  "common": {
    "sideSpacing": "<string>",
    "bottomSpacing": "<string>",
    "width": "<string>",
    "position": "<WidgetSettingsWidgetPosition>",
    "fontFamily": "<string>",
    "primaryColor": {
      "color": "<string>",
      "palette": "<WidgetSettingsColorPalette>"
    },
    "poweredBy": true,
    "launcher": "<WidgetSettingsCommonSettingsLauncher>",
    "footerLink": "<WidgetSettingsCommonSettingsFooterLink>",
    "persistence": "<WidgetSettingsChatPersistence>",
    "featureFlags": "<WidgetSettingsCommonSettingsFeatureFlags>"
  },
  "security": {
    "approvedDomains": "<WidgetSettingsSecuritySettingsApprovedDomains>",
    "disableTranscript": true,
    "isTranscriptDownloadEnabled": true
  }
}
JSON
```


## Get widget snippet

Returns the script tag that embeds the chat widget on a website, filled in for this project and environment, to place before each page's closing body tag.

### Endpoint

```http
GET /v1/stable/widget/snippet
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `version`

Optional · enum<string>

Pins the embed to one version of the environment: `draft`, the version used when testing, or `published`, the version serving live traffic. Omit it to pin the snippet to `published`.

```json
{
  "default": "published",
  "description": "Pins the embed to one version of the environment: `draft`, the version used when testing, or `published`, the version serving live traffic. Omit it to pin the snippet to `published`.",
  "type": "string",
  "enum": [
    "draft",
    "published"
  ],
  "x-enumNames": [
    "DRAFT",
    "PUBLISHED"
  ]
}
```

### Responses

#### 200

Returns the complete `<script>` tag to paste into the website, built from the environment's widget configuration at the requested version.

Schema:

```json
{
  "$ref": "#/components/schemas/StableWidgetGetSnippetResponse"
}
```

Example:

```json
{
  "snippet": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v1/stable/widget/snippet?projectID=<projectID>&environmentAlias=<environmentAlias>&version=<version>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/widget/snippet?projectID=<projectID>&environmentAlias=<environmentAlias>&version=<version>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/widget/snippet?projectID=<projectID>&environmentAlias=<environmentAlias>&version=<version>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf widget get-snippet --project-id <projectID> --environment-alias <environmentAlias> --version <version>
```


## Schema definitions

### StableUpdateResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the update."
    }
  },
  "required": [
    "message"
  ]
}
```

### StableWidget

```json
{
  "type": "object",
  "properties": {
    "type": {
      "description": "Which surface the embed runs: `chat` for a text chat widget, `voice` for a click-to-call widget. It selects whether the `chat` or the `voice` block is applied at runtime; the other is kept but ignored.",
      "allOf": [
        {
          "$ref": "#/components/schemas/WidgetSettingsWidgetType"
        }
      ],
      "enum": [
        "chat",
        "voice"
      ],
      "x-enumNames": [
        "CHAT",
        "VOICE"
      ]
    },
    "chat": {
      "description": "The chat surface, applied when `type` is `chat`: how it renders on the page (floating `widget`, inline `embed`, or `popover`), its header and agent images, the opening banner, the input placeholder, the privacy and AI disclaimers, voice input and output, file upload, and the end-of-conversation CSAT survey.",
      "allOf": [
        {
          "$ref": "#/components/schemas/WidgetSettingsChatSettings"
        }
      ]
    },
    "voice": {
      "description": "The voice surface, applied when `type` is `voice`: how the call screen renders, and the copy shown through a call — the call-to-action, the start and end button labels, and the listening and talking states.",
      "allOf": [
        {
          "$ref": "#/components/schemas/WidgetSettingsVoiceSettings"
        }
      ]
    },
    "common": {
      "description": "Chrome shared by both surfaces: the launcher, the primary color and its palette, the font, the position and spacing on the page, the width, the Voiceflow footer link, and where the conversation is persisted between page loads.",
      "allOf": [
        {
          "$ref": "#/components/schemas/WidgetSettingsCommonSettings"
        }
      ]
    },
    "security": {
      "description": "Approved-domain allowlisting and transcript controls. Absent on a project that has never configured it. Writing this block requires a plan entitlement.",
      "allOf": [
        {
          "$ref": "#/components/schemas/WidgetSettingsSecuritySettings"
        }
      ]
    }
  },
  "required": [
    "type",
    "chat",
    "voice",
    "common"
  ]
}
```

### StableWidgetGetSnippetResponse

```json
{
  "type": "object",
  "properties": {
    "snippet": {
      "type": "string",
      "description": "The complete `<script>` tag to paste into the website, just before the closing `</body>` of every page the widget should appear on. Already filled in with the right verification key, runtime endpoints and render block — it is meant to be copied verbatim, not edited."
    }
  },
  "required": [
    "snippet"
  ]
}
```

### StableWidgetResponse

```json
{
  "type": "object",
  "properties": {
    "widget": {
      "description": "The widget configuration stored on the environment's draft version.",
      "allOf": [
        {
          "$ref": "#/components/schemas/StableWidget"
        }
      ]
    }
  },
  "required": [
    "widget"
  ]
}
```

### StableWidgetUpdateRequest

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "chat",
        "voice"
      ],
      "description": "Switches the embed between the text `chat` surface and the click-to-call `voice` surface. The surface you switch away from is kept as it was, so switching back later restores it.",
      "allOf": [
        {
          "$ref": "#/components/schemas/WidgetSettingsWidgetType"
        }
      ],
      "x-enumNames": [
        "CHAT",
        "VOICE"
      ]
    },
    "chat": {
      "type": "object",
      "properties": {
        "renderMode": {
          "allOf": [
            {
              "$ref": "#/components/schemas/WidgetSettingsChatRenderMode"
            }
          ]
        },
        "headerImage": {
          "allOf": [
            {
              "$ref": "#/components/schemas/WidgetSettingsChatSettingsHeaderImage"
            }
          ]
        },
        "agentImage": {
          "allOf": [
            {
              "$ref": "#/components/schemas/WidgetSettingsChatSettingsAgentImage"
            }
          ]
        },
        "banner": {
          "allOf": [
            {
              "$ref": "#/components/schemas/WidgetSettingsChatSettingsBanner"
            }
          ]
        },
        "placeholderText": {
          "type": "string"
        },
        "disclaimer": {
          "allOf": [
            {
              "$ref": "#/components/schemas/WidgetSettingsChatDisclaimer"
            }
          ]
        },
        "aiDisclaimer": {
          "allOf": [
            {
              "$ref": "#/components/schemas/WidgetSettingsChatSettingsAIDisclaimer"
            }
          ]
        },
        "handoffToAgentImageURL": {
          "nullable": true,
          "type": "string"
        },
        "streamingDisabled": {
          "type": "boolean"
        },
        "responseLoader": {
          "allOf": [
            {
              "$ref": "#/components/schemas/WidgetSettingsChatSettingsResponseLoader"
            }
          ]
        },
        "voiceInput": {
          "type": "boolean"
        },
        "voiceOutput": {
          "type": "boolean"
        },
        "voiceOutputMuted": {
          "type": "boolean"
        },
        "voiceMode": {
          "type": "boolean"
        },
        "notificationSound": {
          "type": "boolean"
        },
        "fileUpload": {
          "allOf": [
            {
              "$ref": "#/components/schemas/WidgetSettingsChatSettingsFileUpload"
            }
          ]
        },
        "csat": {
          "allOf": [
            {
              "$ref": "#/components/schemas/WidgetSettingsChatSettingsCSAT"
            }
          ]
        }
      },
      "description": "Chat-surface fields to change, merged one level deep into the stored `chat` block: what you send replaces its stored counterpart and everything else is kept. A nested object (`banner`, `headerImage`, `disclaimer`, `csat`, …) replaces the stored one outright, so send it complete. `placeholderText` and `aiDisclaimer` need the Webchat Premium entitlement and `disclaimer` the widget-security one: without it the whole request is refused with 403 and nothing is written, including the other fields sent alongside it."
    },
    "voice": {
      "type": "object",
      "properties": {
        "renderMode": {
          "allOf": [
            {
              "$ref": "#/components/schemas/WidgetSettingsVoiceRenderMode"
            }
          ]
        },
        "content": {
          "allOf": [
            {
              "$ref": "#/components/schemas/WidgetSettingsVoiceSettingsContent"
            }
          ]
        }
      },
      "description": "Voice-surface fields to change, merged one level deep into the stored `voice` block. `content` is a nested object: it replaces the stored one outright, so send every line of call-screen copy, not just the one you are changing."
    },
    "common": {
      "type": "object",
      "properties": {
        "sideSpacing": {
          "type": "string"
        },
        "bottomSpacing": {
          "type": "string"
        },
        "width": {
          "type": "string"
        },
        "position": {
          "allOf": [
            {
              "$ref": "#/components/schemas/WidgetSettingsWidgetPosition"
            }
          ]
        },
        "fontFamily": {
          "type": "string"
        },
        "primaryColor": {
          "type": "object",
          "properties": {
            "color": {
              "type": "string",
              "pattern": "^#(?:[\\da-f]{3}|[\\da-f]{6})$",
              "description": "The brand color, as 3- or 6-digit hex. Sent on its own it also regenerates `palette` from itself, which is the only way to recolor the widget without the Webchat Premium entitlement."
            },
            "palette": {
              "description": "The ten shades derived from `color`, keyed `50` through `900`. Send it to override the generated shades — that is the part which needs the Webchat Premium entitlement. Omit it to have it regenerated from `color`.",
              "allOf": [
                {
                  "$ref": "#/components/schemas/WidgetSettingsColorPalette"
                }
              ]
            }
          }
        },
        "poweredBy": {
          "type": "boolean"
        },
        "launcher": {
          "allOf": [
            {
              "$ref": "#/components/schemas/WidgetSettingsCommonSettingsLauncher"
            }
          ]
        },
        "footerLink": {
          "allOf": [
            {
              "$ref": "#/components/schemas/WidgetSettingsCommonSettingsFooterLink"
            }
          ]
        },
        "persistence": {
          "allOf": [
            {
              "$ref": "#/components/schemas/WidgetSettingsChatPersistence"
            }
          ]
        },
        "featureFlags": {
          "allOf": [
            {
              "$ref": "#/components/schemas/WidgetSettingsCommonSettingsFeatureFlags"
            }
          ]
        }
      },
      "description": "Shared-chrome fields to change, merged one level deep into the stored `common` block. A nested object (`launcher`, `footerLink`) replaces the stored one outright, so send it complete. `primaryColor` is the exception and merges too: send `color` on its own to recolor the widget and the shade palette is regenerated from it, send `palette` on its own to hand-tune the shades against the stored color, or send both together. `poweredBy`, `fontFamily`, `footerLink` and `primaryColor.palette` need the Webchat Premium entitlement — `primaryColor.color` on its own does not — and without it the whole request is refused with 403 and nothing is written, including the other fields sent alongside it."
    },
    "security": {
      "description": "Replaces the stored security block in full — unlike the other blocks it has no partial form. Requires a plan entitlement: without one the whole request is refused with 403 and nothing is written, including the other fields sent alongside it.",
      "allOf": [
        {
          "$ref": "#/components/schemas/WidgetSettingsSecuritySettings"
        }
      ]
    }
  },
  "additionalProperties": false
}
```

### WidgetSettingsChatDisclaimer

```json
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "primaryButtonText": {
      "type": "string"
    },
    "secondaryButtonText": {
      "type": "string"
    },
    "secondaryButtonURL": {
      "type": "string"
    }
  },
  "required": [
    "enabled",
    "title",
    "description",
    "primaryButtonText",
    "secondaryButtonText",
    "secondaryButtonURL"
  ]
}
```

### WidgetSettingsChatPersistence

```json
{
  "type": "string",
  "enum": [
    "memory",
    "localStorage",
    "sessionStorage"
  ],
  "x-enumNames": [
    "MEMORY",
    "LOCAL_STORAGE",
    "SESSION_STORAGE"
  ]
}
```

### WidgetSettingsChatRenderMode

```json
{
  "type": "string",
  "enum": [
    "embed",
    "widget",
    "popover"
  ],
  "x-enumNames": [
    "EMBED",
    "WIDGET",
    "POPOVER"
  ]
}
```

### WidgetSettingsChatSettings

```json
{
  "type": "object",
  "properties": {
    "renderMode": {
      "$ref": "#/components/schemas/WidgetSettingsChatRenderMode"
    },
    "headerImage": {
      "$ref": "#/components/schemas/WidgetSettingsChatSettingsHeaderImage"
    },
    "agentImage": {
      "$ref": "#/components/schemas/WidgetSettingsChatSettingsAgentImage"
    },
    "banner": {
      "$ref": "#/components/schemas/WidgetSettingsChatSettingsBanner"
    },
    "placeholderText": {
      "type": "string"
    },
    "disclaimer": {
      "allOf": [
        {
          "$ref": "#/components/schemas/WidgetSettingsChatDisclaimer"
        }
      ]
    },
    "aiDisclaimer": {
      "$ref": "#/components/schemas/WidgetSettingsChatSettingsAIDisclaimer"
    },
    "handoffToAgentImageURL": {
      "nullable": true,
      "type": "string"
    },
    "streamingDisabled": {
      "type": "boolean"
    },
    "responseLoader": {
      "allOf": [
        {
          "$ref": "#/components/schemas/WidgetSettingsChatSettingsResponseLoader"
        }
      ]
    },
    "voiceInput": {
      "type": "boolean"
    },
    "voiceOutput": {
      "type": "boolean"
    },
    "voiceOutputMuted": {
      "type": "boolean"
    },
    "voiceMode": {
      "type": "boolean"
    },
    "notificationSound": {
      "type": "boolean"
    },
    "fileUpload": {
      "allOf": [
        {
          "$ref": "#/components/schemas/WidgetSettingsChatSettingsFileUpload"
        }
      ]
    },
    "csat": {
      "allOf": [
        {
          "$ref": "#/components/schemas/WidgetSettingsChatSettingsCSAT"
        }
      ]
    }
  },
  "required": [
    "renderMode",
    "headerImage",
    "agentImage",
    "banner",
    "placeholderText",
    "aiDisclaimer",
    "voiceInput",
    "voiceOutput"
  ]
}
```

### WidgetSettingsChatSettingsAIDisclaimer

```json
{
  "type": "object",
  "properties": {
    "text": {
      "type": "string"
    },
    "enabled": {
      "type": "boolean"
    }
  },
  "required": [
    "text",
    "enabled"
  ]
}
```

### WidgetSettingsChatSettingsAgentImage

```json
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "url": {
      "nullable": true,
      "type": "string"
    }
  },
  "required": [
    "enabled"
  ]
}
```

### WidgetSettingsChatSettingsBanner

```json
{
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "enabled": {
      "type": "boolean"
    },
    "imageURL": {
      "nullable": true,
      "type": "string"
    }
  },
  "required": [
    "title",
    "description",
    "enabled"
  ]
}
```

### WidgetSettingsChatSettingsCSAT

```json
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "promptText": {
      "type": "string"
    },
    "includeFreetextFeedback": {
      "type": "boolean"
    }
  },
  "required": [
    "enabled",
    "includeFreetextFeedback"
  ]
}
```

### WidgetSettingsChatSettingsFileUpload

```json
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "maxFilesPerConversation": {
      "nullable": true,
      "type": "number"
    },
    "model": {
      "type": "string"
    }
  },
  "required": [
    "enabled"
  ]
}
```

### WidgetSettingsChatSettingsHeaderImage

```json
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "url": {
      "nullable": true,
      "type": "string"
    }
  },
  "required": [
    "enabled"
  ]
}
```

### WidgetSettingsChatSettingsResponseLoader

```json
{
  "oneOf": [
    {
      "$ref": "#/components/schemas/WidgetSettingsChatSettingsResponseLoaderDots"
    },
    {
      "$ref": "#/components/schemas/WidgetSettingsChatSettingsResponseLoaderSpinnerWithText"
    }
  ]
}
```

### WidgetSettingsChatSettingsResponseLoaderDots

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "dots"
      ],
      "x-enumNames": [
        "DOTS"
      ]
    }
  },
  "required": [
    "type"
  ]
}
```

### WidgetSettingsChatSettingsResponseLoaderSpinnerWithText

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "spinner-with-text"
      ],
      "x-enumNames": [
        "SPINNER_WITH_TEXT"
      ]
    },
    "text": {
      "type": "string"
    }
  },
  "required": [
    "type",
    "text"
  ]
}
```

### WidgetSettingsColorPalette

```json
{
  "type": "object",
  "properties": {
    "50": {
      "type": "string"
    },
    "100": {
      "type": "string"
    },
    "200": {
      "type": "string"
    },
    "300": {
      "type": "string"
    },
    "400": {
      "type": "string"
    },
    "500": {
      "type": "string"
    },
    "600": {
      "type": "string"
    },
    "700": {
      "type": "string"
    },
    "800": {
      "type": "string"
    },
    "900": {
      "type": "string"
    }
  },
  "required": [
    "50",
    "100",
    "200",
    "300",
    "400",
    "500",
    "600",
    "700",
    "800",
    "900"
  ]
}
```

### WidgetSettingsCommonSettings

```json
{
  "type": "object",
  "properties": {
    "sideSpacing": {
      "type": "string"
    },
    "bottomSpacing": {
      "type": "string"
    },
    "width": {
      "type": "string"
    },
    "position": {
      "$ref": "#/components/schemas/WidgetSettingsWidgetPosition"
    },
    "fontFamily": {
      "type": "string"
    },
    "primaryColor": {
      "$ref": "#/components/schemas/WidgetSettingsPrimaryColor"
    },
    "poweredBy": {
      "type": "boolean"
    },
    "launcher": {
      "$ref": "#/components/schemas/WidgetSettingsCommonSettingsLauncher"
    },
    "footerLink": {
      "$ref": "#/components/schemas/WidgetSettingsCommonSettingsFooterLink"
    },
    "persistence": {
      "$ref": "#/components/schemas/WidgetSettingsChatPersistence"
    },
    "featureFlags": {
      "allOf": [
        {
          "$ref": "#/components/schemas/WidgetSettingsCommonSettingsFeatureFlags"
        }
      ]
    }
  },
  "required": [
    "sideSpacing",
    "bottomSpacing",
    "position",
    "fontFamily",
    "primaryColor",
    "poweredBy",
    "launcher",
    "footerLink",
    "persistence"
  ]
}
```

### WidgetSettingsCommonSettingsFeatureFlags

```json
{
  "type": "object",
  "additionalProperties": {
    "type": "boolean"
  }
}
```

### WidgetSettingsCommonSettingsFooterLink

```json
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "text": {
      "type": "string"
    },
    "url": {
      "type": "string"
    }
  },
  "required": [
    "enabled"
  ]
}
```

### WidgetSettingsCommonSettingsLauncher

```json
{
  "type": "object",
  "properties": {
    "type": {
      "$ref": "#/components/schemas/WidgetSettingsLauncherType"
    },
    "text": {
      "type": "string"
    },
    "imageURL": {
      "nullable": true,
      "type": "string"
    }
  },
  "required": [
    "type"
  ]
}
```

### WidgetSettingsLauncherType

```json
{
  "type": "string",
  "enum": [
    "icon",
    "label",
    "both"
  ],
  "x-enumNames": [
    "ICON",
    "LABEL",
    "BOTH"
  ]
}
```

### WidgetSettingsPrimaryColor

```json
{
  "type": "object",
  "properties": {
    "color": {
      "type": "string"
    },
    "palette": {
      "$ref": "#/components/schemas/WidgetSettingsColorPalette"
    }
  },
  "required": [
    "color",
    "palette"
  ]
}
```

### WidgetSettingsSecuritySettings

```json
{
  "type": "object",
  "properties": {
    "approvedDomains": {
      "$ref": "#/components/schemas/WidgetSettingsSecuritySettingsApprovedDomains"
    },
    "disableTranscript": {
      "type": "boolean"
    },
    "isTranscriptDownloadEnabled": {
      "type": "boolean"
    }
  },
  "required": [
    "approvedDomains",
    "disableTranscript"
  ]
}
```

### WidgetSettingsSecuritySettingsApprovedDomains

```json
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "domains": {
      "type": "string"
    }
  },
  "required": [
    "enabled",
    "domains"
  ]
}
```

### WidgetSettingsVoiceRenderMode

```json
{
  "type": "string",
  "enum": [
    "full",
    "compact",
    "expand"
  ],
  "x-enumNames": [
    "FULL",
    "COMPACT",
    "EXPAND"
  ]
}
```

### WidgetSettingsVoiceSettings

```json
{
  "type": "object",
  "properties": {
    "renderMode": {
      "$ref": "#/components/schemas/WidgetSettingsVoiceRenderMode"
    },
    "content": {
      "$ref": "#/components/schemas/WidgetSettingsVoiceSettingsContent"
    }
  },
  "required": [
    "renderMode",
    "content"
  ]
}
```

### WidgetSettingsVoiceSettingsContent

```json
{
  "type": "object",
  "properties": {
    "imageURL": {
      "nullable": true,
      "type": "string"
    },
    "talkingText": {
      "type": "string"
    },
    "endButtonText": {
      "type": "string"
    },
    "listeningText": {
      "type": "string"
    },
    "startButtonText": {
      "type": "string"
    },
    "callToActionText": {
      "type": "string"
    }
  },
  "required": [
    "talkingText",
    "endButtonText",
    "listeningText",
    "startButtonText",
    "callToActionText"
  ]
}
```

### WidgetSettingsWidgetPosition

```json
{
  "type": "string",
  "enum": [
    "right",
    "left"
  ],
  "x-enumNames": [
    "RIGHT",
    "LEFT"
  ]
}
```

### WidgetSettingsWidgetType

```json
{
  "type": "string",
  "enum": [
    "chat",
    "voice"
  ],
  "x-enumNames": [
    "CHAT",
    "VOICE"
  ]
}
```
