Overview
An Environment is a separate copy of your agent’s configuration within a project. Each Environment has its own draft, published version and version history, so you can build and test a change while customers continue using a different published version. Every project starts with Main, whose alias is main.
Examples of when to use Environments
Use Environments when a change needs its own place to build, review or release. For example, you could:
- Try a new booking conversation. Revise a Playbook in a separate draft and run representative requests before publishing it.
- Compare two approaches. Publish a candidate and send it a share of new sessions while Main receives the rest.
- Prepare a coordinated release. Collect related changes in one Environment, review them together, then promote the approved version to Main.
- Recover an earlier release. Inspect an Environment’s version history and restore a previously saved version.
How Environments work
Understand drafts, publishing and the separate decision to route traffic.
A draft is the auto-saved configuration you edit. Publishing makes that draft the Environment’s live version and records a release in its version history. Publishing a test Environment does not publish Main.
Traffic splitting routes new sessions to published Environments. Merging takes a source Environment’s live content and replaces Main’s live content. These are separate actions: creating, editing or publishing an Environment does not by itself allocate traffic to it.
What Environments copy and share
An Environment isolates the agent configuration, but some resources still belong to the project. Review this distinction before testing changes against production data.
For credential behavior during publishing, merging and reverting, see Environment-specific Secret values.
How many Environments can a project have?
Check plan-based capacity and what to review before removing an Environment.
The number available depends on your workspace’s plan entitlement. If you reach your limit, review Environments you no longer need before creating another. Removing one also removes its own version history, so check the candidate before deleting it.
Environments best practices
Keep parallel changes reviewable and coordinate their release.
- Give each Environment one reviewable purpose. Keep a release candidate focused on a change you can describe and evaluate, such as appointment reminders. Smaller scopes make the diff and results easier to interpret.
- Keep Main as the release baseline. Coordinate which candidate will be promoted next. Before a merge, compare it with the latest Main so another team’s release is not accidentally replaced.
- Define success before using live traffic. Choose representative conversations and the outcomes you will compare. Use the same checks before and after the change; an Environment is a place to test, not evidence that a change works.
- Clean up with the team. Once a candidate has been promoted or abandoned, check its traffic, integrations and unsaved work before removing it. Keep any history you still need for review.
This page covers Environments with Main. If your project still uses the fixed Development, Staging and Production aliases, follow Migrate to Environments before using this workflow.
How to use Environments
Start in a project that uses Main. This walkthrough creates an isolated draft; publishing it and routing customers to it are later decisions.
Open Environments
Open Environments from the project sidebar. You can also open the Environment switcher beneath the project name and select View all. Review Main and the Environments already in the project.
Configure a clone of Main
Click New environment. Enter a descriptive name, such as Reminder wording, review its generated Alias, and choose Main under Clone from. Confirm the source before continuing.
Create the Environment and check your workspace
Click Create environment. Confirm the new Environment’s name appears in the sidebar before you edit. Open Agent, make the change in its draft, then use Run to check representative conversations. Creating the Environment does not allocate it a share of traffic.
Before publishing, confirm the active Environment, test the changed behavior and review any shared documents or cloned credentials used by your tools.
Creating Environments
Start a separate draft from an existing Environment or saved version.
Create an Environment by cloning an existing one. In Environments, click New environment, enter its name and alias, and select Clone from. The new draft starts from the selected source rather than an empty agent.
To branch from your current working draft while editing, open the arrow beside Publish and select Clone environment. To start from an earlier saved version, open that version in Restoring versions and select Clone to new environment.
After creation, check the Environment name in the sidebar and review the copied configuration before testing it. Pay particular attention to shared resources and cloned Secret values.
Creating Environments best practices
Choose a starting point, name the change and review copied dependencies.
- Choose the source deliberately. A current draft and a saved historical version can contain different changes. Check which one you intend to build on before cloning.
- Name the change, not just the person. A name such as “Booking reminder” helps another reviewer understand why the Environment exists.
- Check dependencies before running tools. Cloning configuration does not create separate external accounts or separate Knowledge base document contents. Review credentials and shared data as part of setup.
Switching Environments
Choose which Environment’s draft you are editing.
The Environment switcher beneath the project name selects the draft you are editing. Open it and choose the Environment you want to work in. The selected name remains visible in the sidebar.
You can edit an Environment that receives live traffic: configuration edits stay in its draft until you publish. Switching the editor does not change traffic allocation. Before editing, publishing or reviewing a diff, check the active name so you are working in the intended Environment.
Does switching Environments move customers too?
Distinguish your editor selection from customer traffic routing.
No. The editor selection chooses your workspace. Customer routing follows the traffic split or an explicit Environment alias supplied by the integration.
Publishing changes
Make an Environment’s draft its published version.
Publishing promotes the selected Environment’s draft to its live version. It replaces that Environment’s previous live content and records a new version in history. Auto-saving a draft does not publish it.
If the Environment receives traffic, publishing changes the version it serves. A protected Environment requires a workspace admin or owner to publish.
Click Publish while editing the Environment. Review the current live version against the draft, enter a version name and description, and confirm Publish. Then open its version history to check the new entry and live marker.
Publishing a candidate does not assign it traffic. Configure Splitting traffic when you are ready to route new sessions to it.
Publishing best practices
Make releases identifiable, review the diff and check live behavior.
- Describe the release. Name the behavior that changed and add enough detail for another person to identify the version later.
- Review the whole diff. Check changes outside the area you edited, especially when several people share the draft.
- Check the live behavior after publishing. Use the intended Environment and representative requests. Keep the previous version identifiable in case you need to restore it.
Discarding unpublished changes
Review what will be removed from the selected draft before confirming.
Discarding changes removes work from the selected draft. Review the diff and preserve anything you still need before confirming.
Open the arrow beside Publish, select Discard changes, review the proposed discard and confirm only when the draft changes can be removed. This is different from reverting a published release. For the treatment of Secret values, see publishing, reverting and discarding Secrets.
Splitting traffic
Route a share of new sessions to each published Environment.
A traffic split assigns a percentage of incoming traffic to each included Environment. Publish the versions you want to compare before routing customers to them.
Open Environments → Edit traffic split. Add the Environments to include, enter their percentages and click Deploy. The total must equal 100%. Removing an Environment from the split stops automatic allocation to it without deleting it.
Changes to a split apply to new sessions; existing sessions continue on their current Environment. The routing is not a way to select named users or cohorts. Use an explicit Environment alias when an integration must target a particular Environment.
Compare results using Analytics, Evaluations and Transcripts, filtered to the Environment and version you are reviewing.
Compare a booking reminder with Main
Explore an illustrative traffic allocation and the outcomes to compare.
Suppose the published Booking reminder candidate changes how appointment requests are confirmed. An illustrative allocation is:
Compare whether conversations collect the intended service and appointment details, and review failures or handoffs as well as successful bookings. These percentages illustrate the configuration; they are not a recommended sample size or evidence of an executed experiment.
If you approve the candidate, merge it into Main. Revisit the traffic allocation after the release so it reflects the next comparison you intend to run.
Traffic splitting best practices
Define a meaningful comparison and verify how each channel routes sessions.
- Compare a meaningful change. Keep the baseline and candidate identifiable so results can be attributed to the intended release.
- Choose measures before deploying the split. Decide which outcomes, errors and handoffs you will inspect. A traffic percentage alone does not establish a statistically reliable result.
- Check each channel’s routing. Traffic splitting is shared across channels. Explicit aliases can pin an integration to an Environment, so confirm which path your Widget, phone or API client uses before interpreting results.
Merging into Main
Replace Main’s live content with an approved candidate.
Merging promotes a source Environment’s live version into Main. Publish the source first if you want its latest draft edits included.
In Environments, open the source row’s menu and choose Merge into main, or use its merge action. Review the two live versions. If Main is protected, a workspace admin or owner must perform the merge.
Main keeps its Secret values unless Override Main secrets is enabled. Review Secret behavior when merging before using that option.
Select Delete environment after merge only if the source and its history are no longer needed. That option also discards unpublished source changes, which are not part of the merge. After merging, check the new entry in Main’s version history and test the promoted behavior.
Merging best practices
Review Main, credentials and source history before promoting a release.
- Recheck Main immediately before promotion. If Main has changed, build from a fresh copy of Main and apply your intended change there before publishing and merging. Do not assume the source contains another team’s recent work.
- Review configuration and credentials separately. The content being promoted and the Secret values used by Main have different merge behavior.
- Keep the source when its history still matters. Automatic deletion is convenient only after you have reviewed draft changes, traffic and integrations that reference it.
Undo a merge into Main
Restore earlier content and check which Secret values remain in use.
A merge creates a new version in Main’s history. To restore the earlier content, open Main’s version history, compare the version before the merge and select Revert. Check the restored behavior afterward. Reverting content preserves the Environment’s current Secret values; it does not roll credentials back.
Restoring versions
Review saved releases and restore the content you need.
Version history records releases for one Environment. In Environments, click the history icon on its row. Review the version name, description, author and time; the live label identifies the current published version.
Select a version to compare it with the Environment’s live content. Click Revert to make the selected content live again; this adds a new history entry. To inspect or extend the old content separately, choose Clone to new environment instead.
Reverting affects only the selected Environment. Its current Secret values remain in place. Review the comparison before confirming a revert, then check the new live entry and run the affected conversations.
Restore a release or investigate a copy?
Choose between replacing current content and inspecting a separate draft.
A clone is useful when you are still diagnosing a change. Check copied credentials and shared resources before running its tools.
Protecting Environments
Restrict publishing and merges to workspace admins and owners.
Environment protection restricts publishing and merging into that Environment to workspace admins and owners. Other members can continue building, editing and testing its draft. Protection is off by default and is set separately for each Environment.
In Environments, open the row’s ••• menu and turn on Environment protection. Only admins and owners can change that protection setting. Check that it is enabled on the intended row.
Protection does not prevent other members from creating Environments or cloning a protected source. It also does not isolate shared Knowledge base document contents.
Environment protection best practices
Choose release destinations to protect and agree on a review handoff.
- Protect important release destinations. Main and other Environments serving customers are useful places to require an admin or owner for publication.
- Agree on a review handoff. Let builders test drafts and provide the intended release and diff to the person who will publish or merge.
- Treat shared resources separately. Protection controls release actions for the Environment; review shared documents and external systems through their own access and change processes.
Environment aliases
Address a specific Environment from your Widget or API client.
An alias is the stable, URL-safe identifier an integration uses to select an Environment. Main’s alias is main. A display-name change does not change the alias.
Review the alias when creating an Environment. Later, copy it from the Alias column in Environments, or choose Copy alias in the row’s menu. Use that exact value when configuring a client that must target the Environment.
For the Widget’s versionID option, see choosing which Environment the Widget loads. For an API integration, use the start-session Environment contract.
Pin a staging Widget to a candidate
Use an explicit alias and check that staging reaches the intended Environment.
Suppose a staging site should always open Booking reminder while the public site follows your traffic split. Configure the staging Widget’s versionID with the candidate’s alias, booking-reminder, following the Widget reference. Keep the public Widget’s routing configuration separate.
Start a fresh conversation from the staging site and check that it reaches the intended Environment. An explicit alias selects the Environment; it does not publish that Environment’s draft or make its configuration a separate external service account.
Can I remove an Environment used by an integration?
Review traffic and pinned clients before deleting their target.
Check its traffic and every integration that uses its alias before deleting it. Removing an Environment from a traffic split is different from deleting it. Update pinned clients to an appropriate published Environment before removing their target.
Related tasks
- Migrate to Environments when your project still uses the legacy aliases.
- Configure Environment-specific Secrets for external services.
- Connect the Widget using an explicit Environment or your traffic split.
- Start a session in an Environment from an API integration.