Documentation Index
Fetch the complete documentation index at: https://docs.voiceflow.com/llms.txt
Use this file to discover all available pages before exploring further.
Main, which is what your users connect to by default.
Key concepts
| Concept | What it is |
|---|---|
| Environment | An independent copy of your agent. |
| Draft version | An auto-saved working version of the environment, updated as you make edits. |
| Live version | The most recently published version of the environment that’s receiving traffic, if configured. |
| Traffic splitting | Control what % of live traffic is reaching which environment. |
| Merging | Promoting a specific environment to Main. |
| Version history | Snapshots of an environments versions over time. |
Best practices
Use the following workflow for any meaningful change to your agent.Main keeps serving users throughout, and you can roll back at any step.
Iterate
Work on the new environment and save ⇧⌘S or publish versions as you go.
Route a small percentage of live traffic
Once you’re happy with the changes, open edit traffic split and send a small percentage of live traffic to the new environment.
View results (A/B test)
Compare this environment to
Main using your KPIs in Analytics, Evaluations and Transcripts.Merge and clean up
If this environments proves to be performing better than Main, merge the environment to
Main. Delete the environment on merge to keep your project clean.Each project supports up to 10 environments, including Main. If you’re close to the limit, merge or delete the ones you no longer need.
Managing environments
You can manage a project’s environments from Settings → Environments when editing a project. Or click the environment name in the left menu under the project name and press ‘view all’.
Creating an environment
Click New environment in the top right. Give the environment a name, pick an environment to Clone from, and click Create.
| Data type | Behaviour when cloning |
|---|---|
| Workflows, playbooks, and tools | Cloned into the new environment. |
| Agent configuration (model, instructions, guardrails) | Cloned into the new environment. |
| Widget settings | Cloned into the new environment. |
| Variables | Cloned into the new environment. |
| Knowledge base documents | The contents of each knowledge base document are shared project-wide. The list of documents included in the original environment is cloned into the new environment. This means that adding or removing documents in the knowledge base is environment-specific, but modifying a document affects all environments that contain that document. |
| Knowledge base metadata | Environment specific. Adding or removing metadata from a document only affects a specific environment. |
| Knowledge base integrations (Shopify and Zendesk) | Shared project-wide. |
| Phone numbers | Shared project-wide, but assigned to a specific environment. |
| Secrets | Shared project-wide, with per-environment overrides available for both draft and live versions of each environment. |
| Evaluations | Shared project wide. Results can be filtered to a specific environment and version. |
| Analytics | Shared project wide. Data can be filtered to a specific environment and version. |
Switching between environments
Use the environment switcher at the top of the sidebar of any page inside your project to switch between environments. You can edit any environment, including ones your users are currently interacting with. Edits only affect the draft version until you publish your environment.
Cloning to new environment
Press the dropdown arrow next to the publish button, and select Clone environment to clone the current draft version to a new environment.
Discarding changes
Press the dropdown arrow next to the publish button, and select Discard changes to open a diff view where you can confirm the selection.
Aliases
Every environment has a short, URL-safe alias used in API calls, the web chat widget, and any other programmatic reference.Main’s alias is main. Aliases don’t change when you rename an environment, so integrations keep working.
Copy an environment’s alias from the Alias column in Settings → Environments.
Legacy projects
Projects created before environments launched use three fixed environments (Development, Staging, and Production) with aliasesdevelopment, staging, and production. These keep working until you opt into migration.
After migrating, update integrations that use the legacy aliases, including the web chat widget snippet. If you’re making use of the start session API endpoint, you’ll also need to update this to point to the main environment, rather than production.