Skip to main content

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.

In April 2026, Voiceflow released a new environments system that replaces the fixed development, staging , and production environments with a flexible, branchable model. Every project now starts with a single environment called main, and you can create more whenever you want to test a change in isolation, compare two versions of your agent against each other, or roll out a new version gradually. Existing projects keep working the way they always have, with the original development, staging and production environments, until you opt in to migrate. Once you migrate a project, the legacy development, staging, and production aliases stop working, so you’ll need to update any integration that points at them. Most projects take a couple of minutes to update.
Migrating without updating your integrations will break your live agent for users. Update every integration that uses the legacy aliases before, or immediately after, you migrate.

​
Update the web chat widget

If you’ve embedded the chat widget on your website, replace your snippet with the new default below (don’t forget to fill in your project’s ID). The new snippet doesn’t include versionID, which means the widget routes each new session according to the traffic split configured in Settings → Environments. For most projects, this is exactly what you want: it automatically respects A/B tests and gradual rollouts. 
<script type="text/javascript">
  (function(d, t) {
      var v = d.createElement(t), s = d.getElementsByTagName(t)[0];
      v.onload = function() {
        window.voiceflow.chat.load({
          verify: { projectID: 'YOUR_PROJECT_ID' },
          url: 'https://general-runtime.voiceflow.com',
          voice: {
            url: "https://runtime-api.voiceflow.com"
          }
        });
      }
      v.src = "https://cdn.voiceflow.com/widget-next/bundle.mjs"; v.type = "text/javascript"; s.parentNode.insertBefore(v, s);
  })(document, 'script');
</script>
You can also find your project’s code snippet in the Widget tab. If you’d rather pin the widget to a specific environment (for example, to load a non-production environment on a staging site), set versionID to that environment’s alias. See our web chat API documentation for more information.

​
Update your Conversations API calls

If you’re calling the Conversations API directly, update any request that passes environment: 'production' by choose one of these options:
  • Updating it to use environment: 'main' instead.
  • Using the traffic split feature by migrating to the new start session and interact endpoints. This is a more intensive process than switching the environment to main, but will give you the ability to A/B test changes prior to release.
For requests that pass 'staging' or 'development', choose whichever option fits best:
  • Point them at 'main' to keep using the same default.
  • Point them at a new environment you create for staging or development work.

​
Migrate your project

Once your integrations are ready, open Settings → General in your project and scroll to the Danger zone section. Click Migrate next to Migrate to environments to switch your project over.
Migration

​
After you migrate

Your agent keeps serving users from main by default. Now you can: