> ## 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. # 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. ## OpenAPI ````yaml /specs-prettified/realtime/openapi.stable.json patch /v1/stable/widget openapi: 3.0.0 info: title: Realtime description: Realtime gateway API service version: 1.0.0 contact: {} servers: - url: https://realtime-api.voiceflow.com security: [] tags: [] paths: /v1/stable/widget: patch: tags: - Widget summary: Update widget description: 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. operationId: StableWidgetController_update parameters: - name: projectID required: true in: query schema: type: string description: The ID of the project to operate on. - name: environmentAlias required: true in: query schema: type: string description: The alias of the environment to operate on (e.g. `main`). requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/StableWidgetUpdateRequest" responses: "200": description: 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. content: application/json: schema: $ref: "#/components/schemas/StableUpdateResponse" x-vf-doc: description: 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. security: - token: [] components: schemas: StableWidgetUpdateRequest: 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 WidgetSettingsWidgetType: type: string enum: - chat - voice x-enumNames: - CHAT - VOICE WidgetSettingsChatRenderMode: type: string enum: - embed - widget - popover x-enumNames: - EMBED - WIDGET - POPOVER WidgetSettingsChatSettingsHeaderImage: type: object properties: enabled: type: boolean url: nullable: true type: string required: - enabled WidgetSettingsChatSettingsAgentImage: type: object properties: enabled: type: boolean url: nullable: true type: string required: - enabled WidgetSettingsChatSettingsBanner: type: object properties: title: type: string description: type: string enabled: type: boolean imageURL: nullable: true type: string required: - title - description - enabled WidgetSettingsChatDisclaimer: 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 WidgetSettingsChatSettingsAIDisclaimer: type: object properties: text: type: string enabled: type: boolean required: - text - enabled WidgetSettingsChatSettingsResponseLoader: oneOf: - $ref: "#/components/schemas/WidgetSettingsChatSettingsResponseLoaderDots" - $ref: "#/components/schemas/WidgetSettingsChatSettingsResponseLoaderSpinnerWith\ Text" WidgetSettingsChatSettingsResponseLoaderDots: type: object properties: type: type: string enum: - dots x-enumNames: - DOTS required: - type WidgetSettingsChatSettingsResponseLoaderSpinnerWithText: type: object properties: type: type: string enum: - spinner-with-text x-enumNames: - SPINNER_WITH_TEXT text: type: string required: - type - text WidgetSettingsChatSettingsFileUpload: type: object properties: enabled: type: boolean maxFilesPerConversation: nullable: true type: number model: type: string required: - enabled WidgetSettingsChatSettingsCSAT: type: object properties: enabled: type: boolean promptText: type: string includeFreetextFeedback: type: boolean required: - enabled - includeFreetextFeedback WidgetSettingsVoiceRenderMode: type: string enum: - full - compact - expand x-enumNames: - FULL - COMPACT - EXPAND WidgetSettingsVoiceSettingsContent: 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: type: string enum: - right - left x-enumNames: - RIGHT - LEFT WidgetSettingsColorPalette: 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" WidgetSettingsCommonSettingsLauncher: type: object properties: type: $ref: "#/components/schemas/WidgetSettingsLauncherType" text: type: string imageURL: nullable: true type: string required: - type WidgetSettingsLauncherType: type: string enum: - icon - label - both x-enumNames: - ICON - LABEL - BOTH WidgetSettingsCommonSettingsFooterLink: type: object properties: enabled: type: boolean text: type: string url: type: string required: - enabled WidgetSettingsChatPersistence: type: string enum: - memory - localStorage - sessionStorage x-enumNames: - MEMORY - LOCAL_STORAGE - SESSION_STORAGE WidgetSettingsCommonSettingsFeatureFlags: type: object additionalProperties: type: boolean WidgetSettingsSecuritySettings: type: object properties: approvedDomains: $ref: "#/components/schemas/WidgetSettingsSecuritySettingsApprovedDomains" disableTranscript: type: boolean isTranscriptDownloadEnabled: type: boolean required: - approvedDomains - disableTranscript WidgetSettingsSecuritySettingsApprovedDomains: type: object properties: enabled: type: boolean domains: type: string required: - enabled - domains StableUpdateResponse: type: object properties: message: type: string description: A human-readable message confirming the update. required: - message securitySchemes: token: scheme: bearer bearerFormat: JWT type: http description: Voiceflow bearer token ````