BotVersion Metadata Type in SFDX & Metadata API

Architectural Overview#

The BotVersion metadata type is the core conversational engine of an Einstein Bot. While the parent Bot metadata file holds org-level wiring (such as the running user and channel bindings), BotVersion stores the entire state machine of a specific bot release: every dialog (BotDialog), step (BotStep), branching rule, variable (ConversationVariable), NLP intent threshold, and backend callout to Flow or ApexClass.

In Salesforce DX source format, BotVersion is decomposed out of the monolithic .bot file into individual <VersionName>.botVersion-meta.xml files inside force-app/main/default/bots/<BotName>/. This enables teams to keep production running on v1.botVersion-meta.xml while developing and testing v2.botVersion-meta.xml in source control.

SFDX Directory & File Suffix#

Key Metadata Fields#

The BotVersion metadata type exposes the following primary XML elements:

Declarative XML & package.xml Examples#

SFDX Source File Example#

<?xml version="1.0" encoding="UTF-8"?>
<BotVersion xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>v1</fullName>
    <botDialogs>
        <botSteps>
            <botMessages>
                <message>Hi! I can help you check your order status.</message>
                <messageIdentifier>msg_welcome_01</messageIdentifier>
            </botMessages>
            <stepIdentifier>step_welcome_01</stepIdentifier>
            <type>Message</type>
        </botSteps>
        <botSteps>
            <botNavigation>
                <botNavigationLinks>
                    <targetBotDialog>Main_Menu</targetBotDialog>
                </botNavigationLinks>
                <type>Redirect</type>
            </botNavigation>
            <stepIdentifier>step_welcome_nav_01</stepIdentifier>
            <type>Navigation</type>
        </botSteps>
        <developerName>Welcome</developerName>
        <isPlaceholderDialog>false</isPlaceholderDialog>
        <label>Welcome</label>
        <showInFooterMenu>false</showInFooterMenu>
    </botDialogs>
    <botDialogs>
        <botSteps>
            <stepIdentifier>step_main_wait_01</stepIdentifier>
            <type>Wait</type>
        </botSteps>
        <developerName>Main_Menu</developerName>
        <isPlaceholderDialog>false</isPlaceholderDialog>
        <label>Main Menu</label>
        <showInFooterMenu>true</showInFooterMenu>
    </botDialogs>
    <conversationVariables>
        <dataType>Text</dataType>
        <developerName>OrderNumber</developerName>
        <label>Order Number</label>
    </conversationVariables>
    <entryDialog>Welcome</entryDialog>
    <intentDisambiguationEnabled>false</intentDisambiguationEnabled>
    <intentThreshold>0.8</intentThreshold>
    <mainMenuDialog>Main_Menu</mainMenuDialog>
    <responseDelayMilliseconds>1000</responseDelayMilliseconds>
    <toneType>Neutral</toneType>
</BotVersion>

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Order_Support_Bot</members>
        <name>Bot</name>
    </types>
    <types>
        <members>Order_Support_Bot.v1</members>
        <name>BotVersion</name>
    </types>
    <version>68.0</version>
</Package>

Querying via SOQL & SFDX CLI#

Audit deployed BotVersion records and check which version is currently active in the target org using SOQL:

SELECT Id, DeveloperName, BotDefinition.DeveloperName, VersionNumber, Status, ToneType
FROM BotVersion
ORDER BY BotDefinition.DeveloperName, VersionNumber DESC

Deploy or retrieve a specific BotVersion:

# Retrieve a single BotVersion along with its parent Bot
sf project retrieve start --metadata Bot:Order_Support_Bot BotVersion:Order_Support_Bot.v1

# Deploy updated BotVersion XML
sf project deploy start --source-dir force-app/main/default/bots/Order_Support_Bot/v1.botVersion-meta.xml

Senior Architect Best Practices & Gotchas#

• Immutable Active Versions: If Order_Support_Bot.v1 has Status = 'Active' in production, deploying edits to v1.botVersion-meta.xml fails with Cannot modify an active bot version. Adopt an immutable version strategy in CI/CD by creating v2.botVersion-meta.xml for major releases.
• Invocable Contract Stability: Changing the input or output parameter signature of an @InvocableMethod in an ApexClass or variable names in an autolaunched Flow referenced by a <botInvocation> breaks BotVersion validation. Always deploy updated Flow/Apex contracts and the updated BotVersion in the same atomic deployment.
• Keep Business Logic Out of Dialog Rules: Avoid building deeply nested conditional rules inside BotVersion XML. Delegate complex routing and data lookups to an autolaunched Flow or Apex service and return a single status variable to the bot.

Frequently asked questions

Where is BotVersion stored in an SFDX project?

In SFDX source format, BotVersion files live inside the parent bot folder at force-app/main/default/bots/BotName/VersionName.botVersion-meta.xml.

Can I deploy changes to an active BotVersion in production?

No. Salesforce blocks metadata modifications to an active BotVersion. You must either deactivate the version before deploying or deploy a new BotVersion such as v2.

How do I reference a specific BotVersion in package.xml?

Use the dot-qualified syntax ParentBotName.VersionDeveloperName inside a BotVersion types block, or retrieve the parent Bot to pull all its versions.

How does BotVersion invoke business logic in Salesforce?

BotVersion steps use BotInvocation to call autolaunched Flows or InvocableMethod Apex classes, passing ConversationVariable values as inputs and outputs.