BotVersion | Metadata API Developer Guide

File Suffix and Directory Location

BotVersion components have the suffix .bot and are stored in the bot folder. BotVersion is a top-level child of Bot and shares its suffix and file directory.

Version

BotVersion components are available in API version 43.0 and later.

Special Access Rules

BotVersion is available only if Live Agent and Einstein Bots are enabled in your org.

Fields

Field Name	Field Type	Description
botDialogGroups	BotDialogGroup[]	The list of dialog groups in this bot version.
botDialogs	BotDialog[]	The list of dialogs in this bot version.
conversationVariables	ConversationVariable[]	A container that stores a specific piece of data collected from the customer. You can use variables within dialog actions as both inputs and outputs. Available in API version 44.0 and later.
entryDialog	string	Required. A reference to the first dialog that the bot presents to your customer. For example, `Welcome`.
mainMenuDialog	string	Required. A reference to the dialog identified as the main menu dialog. For example, `Main Menu`.
responseDelayMilliseconds	int	An optional default or custom delay after every bot response to simulate typing.

BotDialogGroup

The list of dialog groups in this bot version.

Field Name	Field Type	Description
description	string	A description of the bot dialog group.
developerName	string	Required. This unique name prevents conflicts with other dialog groups associated with the same bot version. This name can contain only underscores and alphanumeric characters. The name must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.
label	string	Required. A label that identifies the dialog group throughout the Salesforce user interface.

BotDialog

The list of dialogs in this bot version.

Field Name	Field Type	Description
botDialogGroup	string	The bot dialog group that contains this bot dialog.
botSteps	BotStep[]	A list of steps that are executed as part of the dialog.
description	string	A description of the bot dialog.
developerName	string	Required. This unique name prevents conflicts with other dialogs associated with the same bot version. This name can contain only underscores and alphanumeric characters. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.
label	string	Required. A label that identifies the dialog throughout the Salesforce user interface.
mlIntent	string	Required. The name of the intent associated with a dialog.
showInFooterMenu	boolean	Show this dialog in the Bot Options menu. The default value is `false`.

BotStep

A step that is executed as part of the dialog.

Field Name	Field Type	Description
booleanFilter	string	This field is reserved for future use.
botInvocation	BotInvocation	Bot Invocation used by a BotStep of type `Invocation`.
botMessages	BotMessage[]	List of bot messages used by a BotStep of type `Message`.
botNavigation	BotNavigation	Bot Navigation used by a BotStep of type `Navigation`.
botStepConditions	BotStepCondition[]	List of BotStep conditions associated with a BotStep of type `Group`.
botSteps	BotStep[]	List of BotSteps associated to a Bot Step of type `Group`.
botVariableOperation	BotVariableOperation[]	Bot Variable Operation used by a BotStep of type `VariableOperation`.
type	BotStepType (enumeration of type string)	Required. Valid values are: `Navigation` `Invocation` `VariableOperation` `Message` `Wait` `Group`

BotInvocation

Bot Invocation used by a BotStep of type Invocation.

Field Name	Field Type	Description
invocationActionName	string	Required. The name of the invocable action used by a Bot Invocation.
invocationActionType	ConversationInvocableTargetType	Available dialog action types are: `apex` `flow` `standardInvocableAction`
invocationMappings	BotInvocationMapping[]	List of Bot Invocation Mappings for a Bot Invocation.

BotInvocationMapping

List of Bot Invocation Mappings for a Bot Invocation.

Field Name	Field Type	Description

parameterName	string	Required. Name of an Input/Output parameter of the parent Bot Invocation target.
type	BotInvocationMappingType (enumeration of type string)	Required. Valid values are: `Input` `Output`
value	string	Literal Value to be assigned to to the specified parameter.
variableName	string	Name of the Bot Variable that is used as part of an Invocation mapping.
variableType	ConversationVariableType (enumeration of type string)	Type of the variable used in this invocation mapping. Valid values are: `ConversationVariable` `ContextVariable`

BotMessage

A bot messages used by a BotStep of type Message.

Field Name	Field Type	Description
message	string	Required. Message to display as part of an outgoing message from the bot to the customer.

BotNavigation

Bot navigation used by a BotStep of type Navigation.

Field Name	Field Type	Description
botNavigationLinks	BotNavigationLink[]	List of Bot Navigation links associated with a Bot Navigation of type `Call` or `Redirect`.
type	BotNavigationType (enumeration of type string)	Required. Valid values are: `Call` `Redirect` `TransferToAgent`

BotNavigationLink

List of Bot Navigation links associated with a Bot Navigation of type Call or Redirect.

Field Name	Field Type	Description
label	string	Label displayed when more than one Bot Navigation Link is available under a Bot Navigation of type `Redirect`. The target dialog label is used when no label is provided.
targetBotDialog	string	Required. Name of the target dialog to be called as part of this Bot Navigation Link.

BotStepCondition

List of BotStep conditions associated with a BotStep of type Group.

Field Name	Field Type	Description
operatorType	BotStepConditionOperatorType (enumeration of type string)	Required. Valid values are: `Equals` `NotEquals` `IsSet` `IsNotSet`
rightOperandValue	string	Value that is used as the right side of the condition operation. This value is ignored when using `IsSet` and `IsNotSet` operators.
leftOperandName	string	Required. Name of the variable used as the left side of the condition operation.
leftOperandType	ConversationVariableType (enumeration of type string)	Required. Type of the variable used as the left side of the condition operation. Valid values are: `ConversationVariable` `ContextVariable`

BotVariableOperation

Bot variable operation used by a BotStep of type VariableOperation.

Field Name	Field Type	Description
botInvocation	BotInvocation	Bot Invocation used to provide Dynamic choices by a Bot Variable Operation of type `Collect` and quickReplyType of `Dynamic`.
botMessages	BotMessage[]	List of Bot Messages used as prompt messages by a Bot Variable Operation of type `Collect`.
botQuickReplyOptions	BotQuickReplyOption[]	List of static choice options used by a Bot Variable Operation of type `Collect` and quickReplyType of `Static`.
botVariableOperands	BotVariableOperand[]	List of Bot Variable Operands associated with a Bot Variable of type `Set` or `Unset`.
invalidInputBotNavigation	BotNavigation	Bot Navigation used by a Bot Variable Operation of type `Collect`. This navigation is executed when the associated Bot Invocation doesn’t return any options.
quickReplyOptionTemplate	string	Formula template used to resolve a label for Dynamic choice options of type `Object`.
quickReplyType	BotQuickReplyType (enumeration of type string)	Valid values are: `Static` `Dynamic`
quickReplyWidgetType	BotWidgetType (enumeration of type string)	Valid values are: `Menu` `Buttons`
type	Required. BotVariableOperationType (enumeration of type string)	Valid values are: `Set` `Unset` `Collect`

BotQuickReplyOption

List of static choice options used by a bot variable operation of type Collect and quickReplyType of Static.

Field Name	Field Type	Description
literalValue	string	Required. Value to be displayed as a menu or button choice to your customer.

BotVariableOperand

List of bot variable operands associated with a bot variable of type Set or Unset.

Field Name	Field Type	Description
disableAutoFill	boolean	Disables auto-fill behavior for a bot variable under a bot variable operation of type `Collect`.
sourceName	string	Name of the source CustomField or MlSlotClass used in the variable operation.
sourceType	ConversationVariableOperandSourceType (enumeration of type string)	Valid values are: `StandardConversationVariable` `ConversationVariable` `ContextVariable` Available in API 45.0 and later. `MlSlotClass` `StandardMlSlotClass` `Value`
sourceValue	string	Literal value used as the source for this variable operation.
targetName	string	Required. Name of the target variable used in the variable operation.
targetType	ConversationVariableType (enumeration of type string)	Required. Type of the target used in the variable operation. Valid values are: `ConversationVariable` `ContextVariable`

ConversationVariable

A container that stores a specific piece of data collected from the customer. You can use variables within dialog actions as both inputs and outputs. Available in API version 44.0 and later.

Field Name	Field Type	Description
developerName	string	Required. This name can contain only underscores and alphanumeric characters and must be unique in your org. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.
dataType	ConversationVariableDataType (enumeration of type string)	Required. Valid values are: `Boolean` `Currency` `Date` `DateTime` `Id` (available in API 45.0 and later) `Object` `Number` `Text`
label	string	Label that identifies a variable throughout the Salesforce user interface.

Declarative Metadata Sample Definition

The following is an example of a BotVersion.

1<?xml version="1.0" encoding="UTF-8"?>
2<Bot xmlns="http://soap.sforce.com/2006/04/metadata">
3    <botMlDomain>
4        <label>Astros Pizza</label>
5        <mlIntents>
6            <developerName>New_Order</developerName>
7            <label>New Order</label>
8            <mlIntentUtterances>
9                <utterance>Today is pie day so I want pie</utterance>
10            </mlIntentUtterances>
11        </mlIntents>
12        <mlSlotClasses>
13            <developerName>Size</developerName>
14            <extractionType>Value</extractionType>
15            <label>Size</label>
16            <mlSlotClassValues>
17                <synonymGroup>
18                    <languages>en_US</languages>
19                    <terms>Big</terms>
20                    <terms>Extra Large</terms>
21                    <terms>X-Large</terms>
22                    <terms>Grande</terms>
23                    <terms>Huge</terms>
24                </synonymGroup>
25                <value>Large</value>
26            </mlSlotClassValues>
27        </mlSlotClasses>
28        <name>Astros_Pizza_ld1</name>
29    </botMlDomain>
30    <botVersions>
31        <fullName>v1</fullName>
32        <botDialogGroups>
33            <developerName>Order_Management</developerName>
34            <label>Order Management</label>
35        </botDialogGroups>
36        <botDialogs>
37            <botDialogGroup>Order_Management</botDialogGroup>
38            <botSteps>
39                <botMessages>
40                    <message>🍕🍕🍕Pizza Time! 🍕🍕🍕</message>
41                </botMessages>
42                <type>Message</type>
43            </botSteps>
44            <botSteps>
45                <botStepConditions>
46                    <leftOperandName>Verified_User</leftOperandName>
47                    <leftOperandType>ConversationVariable</leftOperandType>
48                    <operatorType>Equals</operatorType>
49                    <rightOperandValue>false</rightOperandValue>
50                </botStepConditions>
51                <botSteps>
52                    <botNavigation>
53                        <botNavigationLinks>
54                            <targetBotDialog>Customer_Verification</targetBotDialog>
55                        </botNavigationLinks>
56                        <type>Call</type>
57                    </botNavigation>
58                    <type>Navigation</type>
59                </botSteps>
60                <type>Group</type>
61            </botSteps>
62            <botSteps>
63                <botStepConditions>
64                    <leftOperandName>Location</leftOperandName>
65                    <leftOperandType>ConversationVariable</leftOperandType>
66                    <operatorType>IsNotSet</operatorType>
67                </botStepConditions>
68                <botSteps>
69                    <botNavigation>
70                        <botNavigationLinks>
71                            <targetBotDialog>Select_Location</targetBotDialog>
72                        </botNavigationLinks>
73                        <type>Call</type>
74                    </botNavigation>
75                    <type>Navigation</type>
76                </botSteps>
77                <type>Group</type>
78            </botSteps>
79            <botSteps>
80                <botVariableOperation>
81                    <botInvocation>
82                        <invocationActionName>CreateOrderService</invocationActionName>
83                        <invocationActionType>apex</invocationActionType>
84                        <invocationMappings>
85                            <parameterName>customer</parameterName>
86                            <type>Input</type>
87                            <variableName>Contact</variableName>
88                            <variableType>ConversationVariable</variableType>
89                        </invocationMappings>
90                        <invocationMappings>
91                            <parameterName>location</parameterName>
92                            <type>Input</type>
93                            <variableName>Location</variableName>
94                            <variableType>ConversationVariable</variableType>
95                        </invocationMappings>
96                        <invocationMappings>
97                            <parameterName>output</parameterName>
98                            <type>Output</type>
99                            <variableName>Pizza_Order</variableName>
100                            <variableType>ConversationVariable</variableType>
101                        </invocationMappings>
102                    </botInvocation>
103                    <type>Set</type>
104                </botVariableOperation>
105                <type>VariableOperation</type>
106            </botSteps>
107            <botSteps>
108                <botMessages>
109                    <message>Perfect, let&apos;s work on your order from our {!Location.Name} location</message>
110                </botMessages>
111                <type>Message</type>
112            </botSteps>
113            <botSteps>
114                <botNavigation>
115                    <botNavigationLinks>
116                        <targetBotDialog>Add_Items_to_Order</targetBotDialog>
117                    </botNavigationLinks>
118                    <type>Redirect</type>
119                </botNavigation>
120                <type>Navigation</type>
121            </botSteps>
122            <developerName>New_Order</developerName>
123            <label>New Order</label>
124            <mlIntent>New_Order</mlIntent>
125            <showInFooterMenu>false</showInFooterMenu>
126        </botDialogs>
127        <conversationVariables>
128            <dataType>Object</dataType>
129            <developerName>Contact</developerName>
130            <label>Contact</label>
131        </conversationVariables>
132        <conversationVariables>
133            <dataType>Text</dataType>
134            <developerName>Delivery_Address</developerName>
135            <label>Delivery Address</label>
136        </conversationVariables>
137        <conversationVariables>
138            <dataType>Object</dataType>
139            <developerName>Pizza_Order</developerName>
140            <label>Pizza Order</label>
141        </conversationVariables>
142        <entryDialog>Welcome</entryDialog>
143        <mainMenuDialog>Main_Menu</mainMenuDialog>
144    </botVersions>
145    <label>Astro&apos;s Pizza</label>
146</Bot>

The following is an example package.xml that references the previous definition.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>Astros Pizza_Bot.v1</members>
5        <name>BotVersion</name>
6    </types>
7    <version>45.0</version>
8</Package>

Wildcard Support in the Manifest File

This metadata type doesn’t support the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.