BotBlock Metadata Type in SFDX & Metadata API

Architectural Overview#

When scaling Einstein Bots across multiple business units, languages, or regional Service Cloud channels, duplicating common conversational patterns—such as customer identity verification, OTP validation, agent handoff routing, or post-chat CSAT surveys—creates technical debt. The BotBlock metadata type solves this by encapsulating a self-contained group of dialogs, variables, entities, and machine learning intents that can be imported into any Einstein Bot.

Architecturally, BotBlock serves as a composable conversational blueprint. Independent development teams or ISVs can author, version, and distribute a BotBlock via unlocked or managed packages, enabling rapid assembly of enterprise bots with standardized compliance and authentication guardrails.

SFDX Directory & File Suffix#

Key Metadata Fields#

The BotBlock metadata type and its nested BotBlockVersion contain the following key elements:

Declarative XML & package.xml Examples#

SFDX Source File Example#

The following BotBlock packages a reusable post-conversation CSAT survey module:

<?xml version="1.0" encoding="UTF-8"?>
<BotBlock xmlns="http://soap.sforce.com/2006/04/metadata">
    <botBlockVersions>
        <botDialogs>
            <botSteps>
                <botMessages>
                    <message>Before you go, how would you rate your support experience today (1 to 5)?</message>
                    <messageIdentifier>csat_prompt_msg_01</messageIdentifier>
                </botMessages>
                <stepIdentifier>csat_step_01</stepIdentifier>
                <type>Message</type>
            </botSteps>
            <botSteps>
                <stepIdentifier>csat_step_end</stepIdentifier>
                <type>Wait</type>
            </botSteps>
            <developerName>Collect_CSAT_Score</developerName>
            <isPlaceholderDialog>false</isPlaceholderDialog>
            <label>Collect CSAT Score</label>
            <showInFooterMenu>false</showInFooterMenu>
        </botDialogs>
        <conversationVariables>
            <dataType>Number</dataType>
            <developerName>CSAT_Rating</developerName>
            <label>CSAT Rating</label>
        </conversationVariables>
        <description>Standard 5-point CSAT collection dialog for Service Cloud bots.</description>
        <fullName>v1</fullName>
        <status>Active</status>
    </botBlockVersions>
    <description>Reusable CSAT survey block for Enhanced Einstein Bots.</description>
    <label>CSAT Survey Block</label>
    <richContentEnabled>true</richContentEnabled>
</BotBlock>

Package Manifest (package.xml)#

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

SFDX CLI Retrieval & Deployment Commands#

Use the Salesforce CLI to retrieve and deploy BotBlock components across environments:

# Retrieve all BotBlock metadata components in the org
sf project retrieve start --metadata BotBlock

# Deploy a specific BotBlock and its underlying Flow dependencies
sf project deploy start --metadata BotBlock:CSAT_Survey_Block Flow:Record_CSAT_Response

Senior Architect Best Practices & Gotchas#

• Copy-on-Import Semantics: Importing a BotBlock into a bot performs a deep copy of the block’s botDialogs and conversationVariables into the target BotVersion XML. It is not a live runtime reference. If you fix a bug in a BotBlock, you must update the consuming bots as well.
• Placeholder Dialogs for Handoffs: Use <isPlaceholderDialog>true</isPlaceholderDialog> inside a BotBlock when the block needs to transition back to a host bot’s specific dialog (such as Main_Menu or Transfer_To_Agent). The host bot admin then maps the placeholder after importing the block.
• Package External Dependencies Together: If a BotBlock invokes an autolaunched Flow or @InvocableMethod in an ApexClass, bundle those classes and flows in the same unlocked package or manifest so the block never fails deployment due to missing references.

Frequently asked questions

What is the purpose of the BotBlock metadata type?

BotBlock packages a reusable set of bot dialogs, variables, and NLU intents—such as user authentication or CSAT surveys—so architects can import them across multiple Einstein Bots.

Where are BotBlock files stored in SFDX projects?

BotBlock files are stored in the force-app/main/default/botBlocks/ directory with the .botBlock-meta.xml file extension.

Does updating a BotBlock automatically update bots that already imported it?

No. Importing a BotBlock copies its dialogs and variables into the target BotVersion at import time; existing bots must re-import or update their dialog steps directly.

Can a BotBlock contain its ownBotBlockVersion definitions?

Yes, a BotBlock includes a botBlockVersions collection that defines the specific botDialogs, variables, and mlDomain intents packaged inside the block.