Bot Version
A Bot Version in Salesforce is a numbered, saved snapshot of one Einstein Bot or Agentforce agent's configuration.
Definition
A Bot Version in Salesforce is a numbered, saved snapshot of one Einstein Bot or Agentforce agent's configuration. In the Metadata API this is the BotVersion type, and it holds the conversation pieces that change as you build: the dialogs, the conversation variables, the welcome and transfer messages, the entity references, and the intent training that the version uses. A single bot can have many versions over its life, but only one version is active at a time. That active version is the one handling live customer or employee conversations.
The parent Bot record holds the settings that are shared across every version, such as the bot type and whether private data is logged. Each BotVersion holds the parts you iterate on. This split is what lets a team build and test a new version while the current one keeps answering traffic. You activate the new version when it is ready, the previous version steps down to inactive, and you still have it on hand if you need to switch back.
How Bot Versions move from draft to live
Draft, active, and inactive states
A Bot Version lives in one of a few states. A draft is editable and not yet live, so you can change dialogs, add intents, and adjust variables without touching production. When the work is ready you commit the version, which freezes that configuration as a saved snapshot, then you activate it. Activating a version makes it the one bot that customers and employees actually reach. Only one version can be active per bot, so activating a new version automatically steps the previous active version down to inactive. Inactive versions are kept as history. They are not deleted on their own, and you can activate an older one again if you need to. The Agentforce builder makes this sequence explicit with Save for the working draft, Commit Version for the snapshot, and Activate for going live. The legacy Einstein Bot builder uses the same underlying model, with version rows you can clone, activate, and deactivate from the version dropdown. Knowing which state a version is in tells you whether an edit is safe or whether you are about to change something real customers see.
What the BotVersion snapshot captures
The BotVersion metadata type carries the parts of a bot that you actively design. That includes the bot dialogs and the steps inside them, the conversation variables that store data collected during a chat, the welcome message, the transfer conversation message, and references to the entities and intent training the version relies on. Because all of these travel together inside one version, a committed version is a coherent picture of how the bot behaved at that moment. The parent Bot record sits above the versions and holds settings that apply to every version, such as the bot type and data logging preferences, plus context variables defined at the bot level. The practical effect of this split is that version-specific work stays inside the version. You can rework an entire dialog tree in a new draft and the live version is untouched until you activate. When you retrieve or deploy bots with the Metadata API or Salesforce DX, you move Bot and BotVersion together, which is why teams put both under source control and review version diffs before a release.
Cloning a version to start the next one
The usual way to build a new version is to clone the current one rather than edit the live version in place. In the Einstein Bot setup page you open the bot's dropdown in the My Bots list and choose Clone, then give the new bot a unique display name and API name. Cloning copies the configuration and the dialog structure, so the new version starts as a faithful copy and only diverges where you make changes. Routing needs attention after a clone. For enhanced bots, the outbound Omni-Channel flow setting and its routing flows transfer to the clone automatically. The inbound flows that send conversations to the original bot do not transfer, so you have to create or edit those flows in Flow Builder to point traffic at the new bot. You also cannot clone an enhanced bot back into a standard bot. To clone at all you need one of the Customize Application, Modify Metadata, or Manage Bots permissions. Treat the clone as your draft, make your edits there, and leave the live version answering customers until you are ready.
Testing a version before you activate
Activating a version sends it straight to live traffic, so most teams test first. The lightest check is the preview inside the builder, where you type sample messages and watch the dialog respond. That catches obvious dialog and routing mistakes, but it does not reproduce production scale or real customer phrasing. For changes that matter, the safer pattern is to test in a sandbox. You clone the active version in the sandbox, add or adjust intent utterances, train and test there with internal users, then move the version to production. Moving it across happens through an outbound change set: you add the bot first, then click View/Add Dependencies so the change set pulls in the related components, and deploy to production. This keeps risky work out of the live org until it has been exercised. A point worth remembering is about the intent model. If you rebuild the model on an active bot directly, the new build becomes active automatically and you cannot revert to the previous model within that same bot, so clone before you rebuild if you want a fallback.
Rolling back to an earlier version
Because inactive versions are preserved, rollback is usually just activating an older version again. If a freshly activated version misbehaves, you reactivate the prior version and new conversations start using that older configuration. This safety net is the main reason the version model exists: you can ship an ambitious change knowing reversion is a small action rather than a rebuild. There is one important exception to keep in mind. The bot's machine learning intent model does not roll back the same way the dialog configuration does. Once you run a fresh Build Model on an active bot, you cannot return to the previous model inside that same bot, which is why the guidance is to clone the bot before rebuilding so the older model survives on the clone. So rollback of dialogs, variables, and steps is clean through version reactivation, while rollback of the trained model depends on having kept a cloned copy. Planning a deliberate activation window, and watching the bot closely right after, gives you the room to reactivate the previous version quickly if the metrics turn.
Versions in Einstein Bots and in Agentforce
The version concept spans two generations of the product, which is why the term shows up in both Einstein Bots and Agentforce. Einstein Bots, including standard and enhanced bots, use BotVersion rows that you clone, activate, and deactivate from the builder, and you manage their intent through Einstein Intent Sets and the Model Management page. Agentforce builds on the same metadata foundation, so an Agentforce agent is still represented with Bot and BotVersion under the hood, but the builder presents the lifecycle as editable drafts, a Commit Version step, and an Activate action. The rule that only one version is live at a time holds in both. If you are moving from older Einstein Bots toward Agentforce, the mental model carries over: you are still iterating on versions, still keeping one active, and still relying on inactive versions as your history and rollback path. The differences are mostly in the builder experience and in how much of the conversation logic is driven by topics and actions in Agentforce versus structured dialogs in classic Einstein Bots. The versioning discipline you build on one transfers cleanly to the other.
Ship a change as a new Bot Version
Here is the standard, low-risk way to ship a change as a new Bot Version: clone the active version, edit and test the clone, then activate it during a planned window so live traffic moves over cleanly.
- Clone the active version
On the Einstein Bot setup page, open the bot's dropdown in the My Bots list and choose Clone. Give it a unique display name and API name. The clone copies the configuration and dialog structure as your editable draft.
- Make and save your edits
Adjust dialogs, conversation variables, and intent utterances in the cloned draft. Use Einstein Intent Sets to add utterances. The live version keeps answering customers while you work on the draft.
- Test in a sandbox
Activate the draft in a sandbox and run it with internal users, or use the builder preview for quick checks. Validate real phrasing and routing before anything reaches production scale.
- Commit and activate
Commit the version to freeze the snapshot, then click Activate. The previous active version steps down to inactive automatically, and new conversations start on the new version.
- Watch metrics, then prune
Watch bot performance for the first traffic window after activation. Keep the prior version for a short rollback period, then retire stale inactive versions so the list stays readable.
The single committed version currently handling live conversations. Activating a new version moves this status to the new one.
Committed versions no longer live but kept as history. Reactivate one to roll the bot's dialog configuration back.
After cloning an enhanced bot, outbound Omni-Channel routing transfers automatically, but inbound flows must be rebuilt in Flow Builder.
Cloning needs Customize Application, Modify Metadata, or Manage Bots. Confirm the builder has one of these before starting.
- Editing the active version directly changes what live customers see. Clone first and edit the draft instead.
- Rebuilding the intent model on an active bot makes the new build active and you cannot revert to the previous model within that bot. Clone before you rebuild if you want a fallback.
- Inbound routing flows do not transfer when you clone an enhanced bot. New sessions will not reach the clone until you rebuild those flows in Flow Builder.
- Keeping dozens of inactive versions makes the list hard to read and confuses rollback decisions. Retire old ones after the rollback window passes.
Prefer this walkthrough as its own page? How to Bot Version in Salesforce, step by step
Trust & references
Cross-checked against the following references.
- BotVersion | Metadata API Developer GuideSalesforce
- Update an Active Einstein BotSalesforce
Straight from the source - Salesforce's reference material on Bot Version.
- Manage Agent Versions in the Legacy BuilderSalesforce
- Clone an Enhanced BotSalesforce
Hands-on resources to go deeper on Bot Version.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. When you activate a new Bot Version, what happens to the previously active one?
Q2. What does a Bot Version snapshot capture when you clone it for editing?
Q3. Which development pattern keeps Bot Version changes from disrupting live conversations?
Discussion
Loading discussion…