BotSettings Metadata Type in SFDX & Metadata API

Architectural Overview#

The BotSettings metadata type manages the org-wide feature toggle for Salesforce Einstein Bots. In automated CI/CD pipelines and scratch org provisioning workflows, BotSettings is a critical foundational dependency: attempting to deploy Bot, BotVersion, BotBlock, or BotTemplate metadata into an org where enableBots is false results in immediate compilation failure (Required feature is not enabled: Einstein Bots).

By committing Bot.settings-meta.xml into your SFDX repository and pairing it with the Chatbot scratch org feature, DevOps engineers ensure that ephemeral testing environments and newly refreshed sandboxes automatically provision the Einstein Bot runtime and the standard sfdc.chatbot.service.permset permission set before any conversational metadata is deployed.

SFDX Directory & File Suffix#

Key Metadata Fields#

The BotSettings metadata type extends Metadata and exposes the following org-level configuration field:

Declarative XML & package.xml Examples#

SFDX Source File Example#

<?xml version="1.0" encoding="UTF-8"?>
<BotSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableBots>true</enableBots>
</BotSettings>

Package Manifest (package.xml)#

Note that in package.xml, all *Settings metadata types use the Settings type name and strip the Settings suffix from <members>:

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

Scratch Org Definition (project-scratch-def.json)#

{
  "orgName": "Enterprise Service Cloud Scratch Org",
  "edition": "Enterprise",
  "features": ["ServiceCloud", "Chatbot", "LiveAgent"],
  "settings": {
    "botSettings": {
      "enableBots": true
    },
    "omniChannelSettings": {
      "enableOmniChannel": true
    }
  }
}

SFDX CLI Retrieval & Deployment Commands#

Retrieve or deploy BotSettings using the Settings:Bot identifier in Salesforce CLI:

# Retrieve BotSettings from an existing org
sf project retrieve start --metadata Settings:Bot

# Deploy BotSettings before deploying Bot metadata
sf project deploy start --metadata Settings:Bot

Senior Architect Best Practices & Gotchas#

• Manifest Naming Convention: A common CI/CD mistake is specifying <name>BotSettings</name> in package.xml. In Metadata API, settings always use <name>Settings</name> and <members>Bot</members>.
• Omni-Channel Prerequisite for Enhanced Bots: Enhanced Einstein Bots rely on Omni-Channel routing (ServiceChannel and QueueRoutingConfig). Always deploy OmniChannelSettings (enableOmniChannel: true) alongside BotSettings in your foundation deployment stage.
• First-Time Activation Provisioning Delay: When enableBots is flipped from false to true for the first time in an org, Salesforce provisions background chatbot infrastructure and standard permission sets. If a single deployment bundle includes both Settings:Bot and complex Bot definitions that reference sfdc.chatbot.service.permset, deploy Settings:Bot in a pre-deployment step to avoid race conditions.

Frequently asked questions

Why do my Bot or BotVersion deployments fail in a fresh sandbox or scratch org?

If Einstein Bots are not enabled in the target org, deploying Bot metadata fails. Deploying BotSettings with enableBots set to true resolves this prerequisite.

Where is the BotSettings file located in an SFDX project?

It is stored at force-app/main/default/settings/Bot.settings-meta.xml in SFDX source format, or settings/Bot.settings in classic Metadata API format.

How do I enable BotSettings in a scratch org definition file?

In project-scratch-def.json, add botSettings under the settings node with enableBots set to true, and ensure the Chatbot feature is enabled.

Can I disable Einstein Bots via BotSettings while a bot is active?

No. You must first deactivate all active BotVersion records in the org before you can set enableBots to false.