Update widget

curl --request PATCH \
  --url https://realtime-api.voiceflow.com/v1/stable/widget \
  --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
  }
}'

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();

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()

{
  "message": "<string>"
}

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.

PATCH

/v1/stable/widget

Update widget

curl --request PATCH \
  --url https://realtime-api.voiceflow.com/v1/stable/widget \
  --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
  }
}'

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();

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()

{
  "message": "<string>"
}

Authorizations

Authorization

string

header

required

Voiceflow bearer token

Query Parameters

projectID

string

required

The ID of the project to operate on.

environmentAlias

string

required

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

Body

type

enum<string>

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.

Available options: chat, voice

Show child attributes

chat

object

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.

Show child attributes

renderMode

object

Show child attributes

headerImage

object

Show child attributes

enabled

boolean

required

url

string

agentImage

object

Show child attributes

enabled

boolean

required

url

string

banner

object

Show child attributes

title

string

required

description

string

required

enabled

boolean

required

imageURL

string

placeholderText

string

disclaimer

object

Show child attributes

enabled

boolean

required

title

string

required

description

string

required

primaryButtonText

string

required

secondaryButtonText

string

required

secondaryButtonURL

string

required

aiDisclaimer

object

Show child attributes

text

string

required

enabled

boolean

required

handoffToAgentImageURL

string

streamingDisabled

boolean

responseLoader

object

Show child attributes

voiceInput

boolean

voiceOutput

boolean

voiceOutputMuted

boolean

voiceMode

boolean

notificationSound

boolean

fileUpload

object

Show child attributes

enabled

boolean

required

maxFilesPerConversation

number

model

string

csat

object

Show child attributes

enabled

boolean

required

promptText

string

includeFreetextFeedback

boolean

required

voice

object

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.

Show child attributes

renderMode

object

Show child attributes

content

object

Show child attributes

imageURL

string

talkingText

string

required

endButtonText

string

required

listeningText

string

required

startButtonText

string

required

callToActionText

string

required

common

object

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.

Show child attributes

sideSpacing

string

bottomSpacing

string

width

string

position

object

Show child attributes

fontFamily

string

primaryColor

object

Show child attributes

color

string

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

object

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.

Show child attributes

string

required

100

string

required

200

string

required

300

string

required

400

string

required

500

string

required

600

string

required

700

string

required

800

string

required

900

string

required

poweredBy

boolean

launcher

object

Show child attributes

type

object

required

Available options: icon, label, both

text

string

imageURL

string

footerLink

object

Show child attributes

enabled

boolean

required

text

string

url

string

persistence

object

Show child attributes

featureFlags

object

Show child attributes

security

object

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.

Show child attributes

approvedDomains

object

required

Show child attributes

enabled

boolean

required

domains

string

required

disableTranscript

boolean

required

isTranscriptDownloadEnabled

boolean

Response

200 - application/json

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.

message

string

required

A human-readable message confirming the update.

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks

Update widget

Authorizations

Query Parameters

Body

Response

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks