Bot Metadata Type in SFDX & Metadata API

Architectural Overview#

The Bot metadata type represents the top-level definition of an Einstein Bot (Standard or Enhanced) in Salesforce Service Cloud and Digital Engagement. Architecturally, Bot acts as the parent envelope that binds the bot’s security context (botUser), natural language understanding (BotMlDomain), Omni-Channel routing integration, and versioned conversational state machines (BotVersion).

In modern SFDX source format, Bot is decomposed into a dedicated directory under bots/<BotName>/, separating the top-level BotName.bot-meta.xml definition from individual BotVersion XML files. This separation allows conversational designers and developers to iterate on new bot versions without mutating the root bot identity or active routing configurations.

SFDX Directory & File Suffix#

Key Metadata Fields#

The Bot metadata type contains the following key configuration elements:

Declarative XML & package.xml Examples#

SFDX Source File Example#

<?xml version="1.0" encoding="UTF-8"?>
<Bot xmlns="http://soap.sforce.com/2006/04/metadata">
    <botMlDomain>
        <label>Order Support Domain</label>
        <name>Order_Support_Domain</name>
    </botMlDomain>
    <botUser>einstein.bot.integration@acme.enterprise</botUser>
    <contextVariables>
        <contextVariableMappings>
            <SObjectType>MessagingSession</SObjectType>
            <fieldName>MessagingSession.MessagingEndUserId</fieldName>
            <messageType>EmbeddedMessaging</messageType>
        </contextVariableMappings>
        <dataType>Id</dataType>
        <developerName>EndUserId</developerName>
        <label>End User Id</label>
    </contextVariables>
    <description>Enhanced Einstein Bot for order tracking and return authorizations.</description>
    <label>Order Support Bot</label>
    <logPrivateConversationData>true</logPrivateConversationData>
    <richContentEnabled>true</richContentEnabled>
    <sessionTimeout>30</sessionTimeout>
    <type>Bot</type>
</Bot>

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>
    <version>68.0</version>
</Package>

Querying via SOQL & SFDX CLI#

You can inspect deployed Bot records using standard SOQL against BotDefinition:

SELECT Id, DeveloperName, MasterLabel, Description, BotUserId, Type
FROM BotDefinition
ORDER BY DeveloperName ASC

Retrieve or deploy both the Bot and its decomposed BotVersion files with Salesforce CLI:

# Retrieve the Bot and all its BotVersion files
sf project retrieve start --metadata Bot:Order_Support_Bot

# Deploy the Bot container and versions
sf project deploy start --source-dir force-app/main/default/bots/Order_Support_Bot

Senior Architect Best Practices & Gotchas#

• Environment-Specific botUser References: If your bot uses a custom bot user instead of the Basic Chatbot User, <botUser> contains a hardcoded username (e.g., bot@company.com.uat). Use SFDX string replacement in sfdx-project.json so deployments across sandboxes and production do not fail on missing usernames.
• Active Bot Lock: You cannot overwrite an currently active BotVersion in the target org via Metadata API deployment. Deactivate the bot first or deploy changes as a new BotVersion.
• Dependency Ordering: A Bot and its BotVersion often reference Omni-Channel queues, Flows, and Apex classes. Ensure all referenced Flow and ApexClass metadata is included in the same deployment transaction or already exists in the target org.

Frequently asked questions

What is the relationship between Bot and BotVersion metadata?

Bot is the parent container defining global bot settings such as the bot user, label, and rich content support, while BotVersion defines the specific dialog flows, intents, and variables for each version.

Where are Bot metadata files stored in an SFDX project?

In SFDX source format, a Bot is decomposed into force-app/main/default/bots/BotName/ containing BotName.bot-meta.xml and one or more VersionName.botVersion-meta.xml files.

Why does my Bot deployment fail with an invalid botUser error?

The botUser field references a specific Salesforce username that often differs across sandboxes and production. Use environment replacement variables or assign a valid integration user per org.

Can I query Einstein Bot definitions using SOQL or Tooling API?

Yes, you can query the BotDefinition and BotVersion objects to inspect active bots, their DeveloperName, and status across your org.