Endpoint
GET
/v1/stable/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.

Request
Response

Authentication

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

Response

200 - application/json

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

widget
object
required

The widget configuration stored on the environment's draft version.

Endpoint
PATCH
/v1/stable/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.

Request
Response

Authentication

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

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

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.

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.

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.

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.

Endpoint
GET
/v1/stable/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.

Request
Response

Authentication

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

version
enum<string>
default:"published"

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.

Available options: draft, published

Response

200 - application/json

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

snippet
string
required

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.

Schemas

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.