How a change reaches real users, and the channels it reaches them through, one section per term.

Environments

Environment

One draft-and-published copy of the agent. Main, plus up to nine more. Each has an auto-saved draft version and the published version live traffic reaches, and its own short alias.

Also asked as:

a staging copy of the assistant
work on changes without touching what customers see
how many copies of the agent can a project have

Related: Draft version · Publishing · Merging · Alias · Environment protection

Documented in: Environments › Key concepts · Environments › Creating an environment · Environments › Best practices · Publishing (API)

Draft version

The auto-saved working version of an environment, updated as you edit. It becomes the published version when you publish; Discard changes throws it away after a diff review.

Also asked as:

my unsaved edits versus what is live
undo everything since the last publish
where do my changes sit before I ship them

Related: Environment · Publishing

Documented in: Environments › Key concepts · Environments › Discarding changes

Publishing

Promoting an environment’s draft to its published version, which is the copy live traffic reaches. The publish view shows a side-by-side diff first. Widget settings also take effect only after a publish.

Also asked as:

push my changes live
make the new version the one customers get
why isn’t my edit showing up on the website

Related: Draft version · Environment protection · Merging

Documented in: Publishing › Publishing a new version · Customize widget › Publishing changes

Merging

Folding work done in one environment back into another. A merge uses the source environment’s live version, not its draft, and replaces the content of Main.

Also asked as:

bring my staging changes into main
combine two copies of the agent
promote a branch

Documented in: Merging › Things to know before you merge to Main · Merging › Merging to main · vf environment merge

Reverting a merge

Undoing a merge into Main by restoring the pre-merge version from Main’s version history, since a merge is just a new version.

Also asked as:

roll back a bad merge
restore main to how it was before
undo the release we just made

Related: Merging · Version history

Documented in: Merging › Reverting a merge

Version history

The list of published versions of an environment, from which any earlier version can be restored.

Also asked as:

go back to a previous published version
see what was live last week
roll back to an earlier version
see every version I published

Related: Publishing · Reverting a merge

Documented in: Environments › Key concepts · Merging › Reverting a merge · Version history

Cloning an environment

Creating a new environment from an existing one, either from Settings → Environments (New environment, pick what to clone from) or from the publish dropdown (Clone environment, which copies the current draft).

Also asked as:

make a copy of main to try something
duplicate an environment
copy the live agent into a sandbox
spin up a test copy from main

Related: Environment · Traffic split

Documented in: Environments › Creating an environment · Environments › Cloning to new environment

Environment protection

Protecting an environment restricts who can change what your users see: on a protected environment, only workspace admins and owners can publish or merge into it.

Also asked as:

lock main so nobody ships to it by mistake
require an admin to publish production
prevent accidental deploys to the live copy
prevent a careless publish to the live environment
only admins should be able to publish production
nobody can accidentally deploy to the live environment

Related: Publishing · Role · Environment

Documented in: Environments › Environment protection

Alias

Every environment’s short, URL-safe name used in API calls, the chat widget and any other programmatic reference. Main’s alias is main. Aliases don’t change when an environment is renamed.

Also asked as:

the environment name I put in the API URL
point the widget at a specific environment
what is main in the request path

Related: Environment · Chat widget API

Documented in: Environments › Aliases · Chat widget API › Choosing which environment the widget loads

Legacy projects

Projects created before environments launched, which use three fixed environments — Development, Staging and Production — with the aliases development, staging and production.

Also asked as:

my project still shows development, staging and production
old-style environments
my older project has development, staging and production
the three fixed environments

Related: Environment · Alias

Documented in: Environments › Legacy projects

Traffic split

Sending a share of live conversations to a different environment, to compare two versions against real traffic or roll a change out gradually. Users are routed automatically; you cannot pick which users land where.

Also asked as:

A/B test two versions of the assistant
send a percentage of customers to the new version
canary release for the agent
roll a new version out to a small percentage of users first
send some traffic to the new environment

Related: Environment · Cloning an environment · Analytics

Documented in: A/B testing › When to use a traffic split · A/B testing › Editing traffic split · A/B testing › Considerations

The embeddable chat surface. Always “chat widget”; older material says “Webchat”. It is added to a site with the snippet from the Widget tab once a version of the agent is published.

Also asked as:

get the chat launcher onto our homepage
embed the assistant on a page
the script tag for the chat window
show the chat launcher on every page of our site
install the widget on a web page
the chat bubble in the corner of the site

Related: Chat widget API · Widget customization · Publishing

Documented in: Install widget › Adding the widget to your website · Chat widget API › Understanding the default snippet

Matching the widget to your brand from the Widget settings page — colours, icons, launcher style, modality (chat or voice), file uploads, security settings — or, for developers, through the chat.load() configuration and custom CSS.

Also asked as:

change the chat window’s colours and logo
match the widget to our brand
style the launcher button

Related: Chat widget · Custom CSS · Chat widget API

Documented in: Customize widget › Customizing your widget · Customize widget › Using built-in styling options · Customize widget › Appearance

Custom CSS

CSS rules that override the widget’s default styles, targeting its supported vfrc- class names and loaded as a hosted stylesheet or inline.

Also asked as:

style the chat window beyond the built-in options
override the widget’s fonts and spacing
the CSS classes the widget exposes

Related: Widget customization

Documented in: Customize widget › Applying custom CSS · Customize widget › Supported CSS classes · Customize widget › Loading your stylesheet

The assistant object in chat.load(): widget type and render mode, header image and title, the welcome banner, the agent avatar, the input placeholder, the launcher (icon or label), the footer link, the brand colour and full palette, the position and spacing, the AI disclaimer, streaming, and persistence — every visual and behavioural override, applied locally over the published settings.

Also asked as:

hide the AI disclaimer in the widget
move the chat launcher to the left side
change the header title and avatar with code
turn off the streaming animation

Related: Widget customization · Chat widget API · Custom CSS

Documented in: Customize widget › Visual & behavioural overrides · Customize widget › Launcher · Customize widget › AI disclaimer · Customize widget › Position · Customize widget › color · Customize widget › Behavior

Dangerous HTML

An opt-in that lets the widget render raw HTML elements in messages. Only for trusted code that you control, because of XSS risk.

Also asked as:

render HTML inside a chat message
the widget strips my tags

Related: Chat widget API · Chat widget extensions

Documented in: Chat widget API › Allowing dangerous HTML elements

Runtime URL

The url property in chat.load() that points the widget at a private runtime endpoint. Only for Enterprise customers hosted on a Private Cloud.

Also asked as:

point the widget at our private cloud
the widget must talk to a different runtime

Related: Chat widget API

Documented in: Chat widget API › Setting the runtime URL

Whether the widget runs in chat or voice mode, set in Widget → Modality & Interface. Voice mode brings voice output, voice input and audio cues to a chat project.

Also asked as:

let visitors talk to the assistant instead of typing
voice mode in the website widget
switch the website widget to voice
let visitors speak to the assistant in the browser

Related: Chat widget · Voice output

Documented in: Customize widget › Choosing a modality

File uploads

Letting users attach files (PDF, JPEG, PNG, WEBP, up to 5 MB each) to their messages so the agent can read and act on them; files are stored in Voiceflow’s private storage.

Also asked as:

let customers send a screenshot or a PDF
attach a document in the chat
where do uploaded files go

Related: Chat widget · Live agent handoff step

Documented in: Customize widget › Enabling file uploads · Customize widget › Supported files and limits · Customize widget › File storage and privacy

Approved domains

The widget’s security settings: approved domains restrict where the widget can load, alongside the other options at the bottom of the widget settings page.

Also asked as:

only allow the widget on our own domain
stop someone embedding our bot on their site
restrict which websites can load the widget
prevent the chat from being embedded elsewhere

Related: Chat widget

Documented in: Customize widget › Configuring security settings

window.voiceflow.chat, the widget’s JavaScript API: the load configuration (environment, runtime URL, persistence, user ID, launch variables, transcript metadata), methods to open, close and send messages, proactive messages, and events you can listen for.

Also asked as:

open the chat window from my own button
send data from my site into the conversation
control the widget with JavaScript

Related: Chat widget · Proactive messages · Chat widget extensions · User ID

Documented in: Chat widget API › API methods · Chat widget API › Passing custom variables · Chat widget API › Listening for events · Chat widget API › Annotating transcripts with metadata · Chat widget API › Setting the runtime URL

Proactive messages

Messages the widget shows outside the chat window before the user opens it, pushed with window.voiceflow.chat.proactive.push() and cleared with proactive.clear(), often triggered by user behaviour on the page.

Also asked as:

show a message bubble before the visitor clicks the chat
nudge people on the pricing page
greet users proactively on the site

Related: Chat widget API

Documented in: Chat widget API › Sending proactive messages · Chat widget API › Triggering messages based on user behavior

Custom code registered in chat.load() that renders interactive widgets inside the chat (response extensions) or runs side effects (effect extensions), triggered by a custom trace from a function.

Also asked as:

put a form or a date picker inside the chat
render my own component in a reply
custom UI in the widget

Related: Chat widget API · Function · Trace

Documented in: Chat widget extensions › Extension types · Chat widget extensions › How extensions work · Chat widget extensions › Registering extensions

Phone and SMS

Phone number

A number connected to a project — a Voiceflow number or one from your own provider — that routes incoming calls and texts to an environment, can be reused across projects, recorded, and removed again.

Also asked as:

get a number for the voice agent
hook the assistant up to our existing phone line
take a number off a project
unlink a number we no longer need
detach a phone number from a project

Related: Inbound calling · Outbound calling · Call recording · Add-on

Documented in: Connecting a phone number › Adding a phone number · Connecting a phone number › Routing calls to an environment · Connecting a phone number › Removing a phone number · Connecting a phone number › Assigning an existing number

Call recording

Recording calls for quality assurance from the phone number’s settings; complying with recording and consent laws in your region is your responsibility.

Also asked as:

keep audio of the calls the agent takes
listen back to a conversation
record phone conversations with the agent
play back a call afterwards

Related: Phone number · Transcript

Documented in: Connecting a phone number › Enabling call recording

Inbound calling

How a call to a connected number is handled: routed to an assigned environment or by the traffic split, with the caller’s number set as user_id. A non-production number can point at an environment’s draft to test changes by phone.

Also asked as:

test my changes by ringing the agent myself
call a draft version without affecting real callers
which environment picks up the phone
dial the draft version myself before customers get it

Related: Phone number · User ID · Traffic split

Documented in: Inbound calling › How it works · Inbound calling › Testing draft changes by phone · Inbound calling › Testing changes with real callers

Outbound calling

Programmatically making the agent call a number: a POST to the phone number’s outbound endpoint with the Dialog Manager API key, the destination, optional variables and answering-machine detection. Outbound and inbound calls share one concurrency pool.

Also asked as:

have the assistant dial a customer
start a call from our server
the limit on simultaneous dials
kick off a call to someone from our own system with data attached
how many outbound calls at the same time

Related: Phone number · Outbound SMS · Dialog Manager API key

Documented in: Outbound calling › Making an outbound call · Outbound calling › Request body · Outbound calling › Concurrency limits

SMS

The SMS channel for your agent. People text your Twilio number, or your agent texts them first with outbound SMS. SMS assignment to an environment is independent of voice assignment.

Also asked as:

let customers text the assistant
reply to messages sent to our number
SMS and voice on the same number

Related: Outbound SMS · Phone number

Documented in: Inbound SMS › How it works · Inbound SMS › Testing draft changes by SMS · Connecting a phone number › Routing SMS to an environment · Inbound SMS › Testing changes with real users

Outbound SMS

Starting a text conversation from your side: a POST to the number’s outbound SMS endpoint, which returns 202 with the new session ID and sends the first text once the agent has run its launch path.

Also asked as:

send the first text message to a customer
trigger an SMS conversation from our system
send the first text to a customer proactively
start a text conversation from our side

Related: SMS · Outbound calling

Documented in: Outbound SMS › Starting an outbound conversation · Outbound SMS › Response

Deploy

Environments

Environment

Draft version

Publishing

Merging

Reverting a merge

Version history

Cloning an environment

Environment protection

Alias

Legacy projects

Traffic split

Chat widget

Chat widget

Widget customization

Custom CSS

Widget configuration

Dangerous HTML

Runtime URL

Widget modality

File uploads

Approved domains

Chat widget API

Proactive messages

Chat widget extensions

Phone and SMS

Phone number

Call recording

Inbound calling

Outbound calling

SMS

Outbound SMS