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

# Deploy

> Environments, publishing, merging and traffic splits: how a change reaches real users, and the channels it reaches them through.

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](#draft-version) · [Publishing](#publishing) · [Merging](#merging) · [Alias](#alias) · [Environment protection](#environment-protection)

**Documented in:** [Environments › Key concepts](/docs/documentation/deploy/environments/overview#key-concepts) · [Environments › Creating an environment](/docs/documentation/deploy/environments/overview#creating-an-environment) · [Environments › Best practices](/docs/documentation/deploy/environments/overview#best-practices) · [Publishing (API)](/docs/api-reference/sections/publishing)

### 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](#environment) · [Publishing](#publishing)

**Documented in:** [Environments › Key concepts](/docs/documentation/deploy/environments/overview#key-concepts) · [Environments › Discarding changes](/docs/documentation/deploy/environments/overview#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](#draft-version) · [Environment protection](#environment-protection) · [Merging](#merging)

**Documented in:** [Publishing › Publishing a new version](/docs/documentation/deploy/environments/publishing#publishing-a-new-version) · [Customize widget › Publishing changes](/docs/documentation/deploy/widget/custom-web-chat-styling#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

**Related:** [Reverting a merge](#reverting-a-merge) · [Environment](#environment) · [Secrets across environments](/docs/resources/glossary/knowledge-and-data#secrets-across-environments)

**Documented in:** [Merging › Things to know before you merge to Main](/docs/documentation/deploy/environments/merging#things-to-know-before-you-merge-to-main) · [Merging › Merging to main](/docs/documentation/deploy/environments/merging#merging-to-main) · [vf environment merge](/docs/cli/commands/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](#merging) · [Version history](#version-history)

**Documented in:** [Merging › Reverting a merge](/docs/documentation/deploy/environments/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](#publishing) · [Reverting a merge](#reverting-a-merge)

**Documented in:** [Environments › Key concepts](/docs/documentation/deploy/environments/overview#key-concepts) · [Merging › Reverting a merge](/docs/documentation/deploy/environments/merging#reverting-a-merge) · [Version history](/docs/documentation/deploy/environments/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](#environment) · [Traffic split](#traffic-split)

**Documented in:** [Environments › Creating an environment](/docs/documentation/deploy/environments/overview#creating-an-environment) · [Environments › Cloning to new environment](/docs/documentation/deploy/environments/overview#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](#publishing) · [Role](/docs/resources/glossary/core-objects#role) · [Environment](#environment)

**Documented in:** [Environments › Environment protection](/docs/documentation/deploy/environments/overview#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](#environment) · [Chat widget API](#chat-widget-api)

**Documented in:** [Environments › Aliases](/docs/documentation/deploy/environments/overview#aliases) · [Chat widget API › Choosing which environment the widget loads](/docs/documentation/deploy/widget/web-chat-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](#environment) · [Alias](#alias)

**Documented in:** [Environments › Legacy projects](/docs/documentation/deploy/environments/overview#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](#environment) · [Cloning an environment](#cloning-an-environment) · [Analytics](/docs/resources/glossary/measure#analytics)

**Documented in:** [A/B testing › When to use a traffic split](/docs/documentation/deploy/environments/traffic-split#when-to-use-a-traffic-split) · [A/B testing › Editing traffic split](/docs/documentation/deploy/environments/traffic-split#editing-traffic-split) · [A/B testing › Considerations](/docs/documentation/deploy/environments/traffic-split#considerations)

## Chat widget

### Chat widget

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](#chat-widget-api) · [Widget customization](#widget-customization) · [Publishing](#publishing)

**Documented in:** [Install widget › Adding the widget to your website](/docs/documentation/deploy/widget/embedding-the-chat-widget#adding-the-widget-to-your-website) · [Chat widget API › Understanding the default snippet](/docs/documentation/deploy/widget/web-chat-api#understanding-the-default-snippet)

### Widget customization

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](#chat-widget) · [Custom CSS](#custom-css) · [Chat widget API](#chat-widget-api)

**Documented in:** [Customize widget › Customizing your widget](/docs/documentation/deploy/widget/custom-web-chat-styling#customizing-your-widget) · [Customize widget › Using built-in styling options](/docs/documentation/deploy/widget/custom-web-chat-styling#using-built-in-styling-options) · [Customize widget › Appearance](/docs/documentation/deploy/widget/custom-web-chat-styling#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](#widget-customization)

**Documented in:** [Customize widget › Applying custom CSS](/docs/documentation/deploy/widget/custom-web-chat-styling#applying-custom-css) · [Customize widget › Supported CSS classes](/docs/documentation/deploy/widget/custom-web-chat-styling#supported-css-classes) · [Customize widget › Loading your stylesheet](/docs/documentation/deploy/widget/custom-web-chat-styling#loading-your-stylesheet)


### Widget configuration

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](#widget-customization) · [Chat widget API](#chat-widget-api) · [Custom CSS](#custom-css)

**Documented in:** [Customize widget › Visual & behavioural overrides](/docs/documentation/deploy/widget/custom-web-chat-styling#visual-&-behavioural-overrides) · [Customize widget › Launcher](/docs/documentation/deploy/widget/custom-web-chat-styling#launcher) · [Customize widget › AI disclaimer](/docs/documentation/deploy/widget/custom-web-chat-styling#ai-disclaimer) · [Customize widget › Position](/docs/documentation/deploy/widget/custom-web-chat-styling#position) · [Customize widget › color](/docs/documentation/deploy/widget/custom-web-chat-styling#color) · [Customize widget › Behavior](/docs/documentation/deploy/widget/custom-web-chat-styling#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-api) · [Chat widget extensions](#chat-widget-extensions)

**Documented in:** [Chat widget API › Allowing dangerous HTML elements](/docs/documentation/deploy/widget/web-chat-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](#chat-widget-api)

**Documented in:** [Chat widget API › Setting the runtime URL](/docs/documentation/deploy/widget/web-chat-api#setting-the-runtime-url)

### Widget modality

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](#chat-widget) · [Voice output](/docs/resources/glossary/build#voice-output)

**Documented in:** [Customize widget › Choosing a modality](/docs/documentation/deploy/widget/custom-web-chat-styling#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](#chat-widget) · [Live agent handoff step](/docs/resources/glossary/build#live-agent-handoff-step)

**Documented in:** [Customize widget › Enabling file uploads](/docs/documentation/deploy/widget/custom-web-chat-styling#enabling-file-uploads) · [Customize widget › Supported files and limits](/docs/documentation/deploy/widget/custom-web-chat-styling#supported-files-and-limits) · [Customize widget › File storage and privacy](/docs/documentation/deploy/widget/custom-web-chat-styling#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](#chat-widget)

**Documented in:** [Customize widget › Configuring security settings](/docs/documentation/deploy/widget/custom-web-chat-styling#configuring-security-settings)

### Chat widget API

`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](#chat-widget) · [Proactive messages](#proactive-messages) · [Chat widget extensions](#chat-widget-extensions) · [User ID](/docs/resources/glossary/core-objects#user-id)

**Documented in:** [Chat widget API › API methods](/docs/documentation/deploy/widget/web-chat-api#api-methods) · [Chat widget API › Passing custom variables](/docs/documentation/deploy/widget/web-chat-api#passing-custom-variables) · [Chat widget API › Listening for events](/docs/documentation/deploy/widget/web-chat-api#listening-for-events) · [Chat widget API › Annotating transcripts with metadata](/docs/documentation/deploy/widget/web-chat-api#annotating-transcripts-with-metadata) · [Chat widget API › Setting the runtime URL](/docs/documentation/deploy/widget/web-chat-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](#chat-widget-api)

**Documented in:** [Chat widget API › Sending proactive messages](/docs/documentation/deploy/widget/web-chat-api#sending-proactive-messages) · [Chat widget API › Triggering messages based on user behavior](/docs/documentation/deploy/widget/web-chat-api#triggering-messages-based-on-user-behavior)

### Chat widget extensions

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](#chat-widget-api) · [Function](/docs/resources/glossary/build#function) · [Trace](/docs/resources/glossary/developer-surfaces#trace)

**Documented in:** [Chat widget extensions › Extension types](/docs/documentation/deploy/widget/web-chat-extensions#extension-types) · [Chat widget extensions › How extensions work](/docs/documentation/deploy/widget/web-chat-extensions#how-extensions-work) · [Chat widget extensions › Registering extensions](/docs/documentation/deploy/widget/web-chat-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](#inbound-calling) · [Outbound calling](#outbound-calling) · [Call recording](#call-recording) · [Add-on](/docs/resources/glossary/core-objects#add-on)

**Documented in:** [Connecting a phone number › Adding a phone number](/docs/documentation/deploy/phone/connect-a-phone-number#adding-a-phone-number) · [Connecting a phone number › Routing calls to an environment](/docs/documentation/deploy/phone/connect-a-phone-number#routing-calls-to-an-environment) · [Connecting a phone number › Removing a phone number](/docs/documentation/deploy/phone/connect-a-phone-number#removing-a-phone-number) · [Connecting a phone number › Assigning an existing number](/docs/documentation/deploy/phone/connect-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](#phone-number) · [Transcript](/docs/resources/glossary/measure#transcript)

**Documented in:** [Connecting a phone number › Enabling call recording](/docs/documentation/deploy/phone/connect-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](#phone-number) · [User ID](/docs/resources/glossary/core-objects#user-id) · [Traffic split](#traffic-split)

**Documented in:** [Inbound calling › How it works](/docs/documentation/deploy/phone/inbound-calling#how-it-works) · [Inbound calling › Testing draft changes by phone](/docs/documentation/deploy/phone/inbound-calling#testing-draft-changes-by-phone) · [Inbound calling › Testing changes with real callers](/docs/documentation/deploy/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](#phone-number) · [Outbound SMS](#outbound-sms) · [Dialog Manager API key](/docs/resources/glossary/developer-surfaces#dialog-manager-api-key)

**Documented in:** [Outbound calling › Making an outbound call](/docs/documentation/deploy/phone/outbound-calling#making-an-outbound-call) · [Outbound calling › Request body](/docs/documentation/deploy/phone/outbound-calling#request-body) · [Outbound calling › Concurrency limits](/docs/documentation/deploy/phone/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](/docs/documentation/deploy/sms/outbound). 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](#outbound-sms) · [Phone number](#phone-number)

**Documented in:** [Inbound SMS › How it works](/docs/documentation/deploy/sms/inbound#how-it-works) · [Inbound SMS › Testing draft changes by SMS](/docs/documentation/deploy/sms/inbound#testing-draft-changes-by-sms) · [Connecting a phone number › Routing SMS to an environment](/docs/documentation/deploy/phone/connect-a-phone-number#routing-sms-to-an-environment) · [Inbound SMS › Testing changes with real users](/docs/documentation/deploy/sms/inbound#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](#sms) · [Outbound calling](#outbound-calling)

**Documented in:** [Outbound SMS › Starting an outbound conversation](/docs/documentation/deploy/sms/outbound#starting-an-outbound-conversation) · [Outbound SMS › Response](/docs/documentation/deploy/sms/outbound#response)