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 Chat 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.
conversationSystemDialogs	ConversationSystemDialog[]	A system function assigned to a dialog. Available in API version 48.0 and later.
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`.
nlpProviders	ConversationDefinitionNlpProvider[]	Defines the language provider which is used for a particular language. Available in API version 49.0 and later.
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.
mlIntentTrainingEnabled	boolean	Indicates whether Einstein is turned on to train an intent model for the dialog intent (`true`) or turned off for the exact match option (`false`). The default value is `false`.Available in API version 46.0 and later.
showInFooterMenu	boolean	Indicates whether to 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`.
conversationRecordLookup	ConversationRecordLookup []	A lookup action to the Conversation record. Available in API version 46.0 and later.
conversationSystemMessage	ConversationSystemMessage[]	System messages that represent an action for a Bot Step, such as transferring to an agent or ending a chat. Available in API version 46.0 and later.
type	BotStepType (enumeration of type string)	Required. Valid values are: `Navigation` `Invocation` `VariableOperation` `Message` `Wait` `Group` `RecordLookup` (Available in API version 48.0 and later.)

BotInvocation

Bot Invocation used by a BotStep of type Invocation.

Field Name	Field Type	Description
invocationActionName	string	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 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)	This field relates to the type of variable used in this invocation mapping. Valid values are: `ConversationVariable` `ContextVariable`

BotMessage

A bot message 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
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`
operatorType	BotStepConditionOperatorType (enumeration of type string)	Required. Valid values are: `Equals` `NotEquals` `IsSet` `IsNotSet` `GreaterThan` (Available in API version 47.0 and later.) `LessThan` (Available in API version 47.0 and later.) `GreaterThanOrEqualTo` (Available in API version 47.0 and later.) `LessThanOrEqualTo` (Available in API version 47.0 and later.)
rightOperandValue	string	Value that is used as the right side of the condition operation. This value is ignored when using `IsSet` and `IsNotSet` operators.

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.
optionalCollect	boolean	If `true`, the bot asks the repair attempts once and then moves on to the next dialog step. The default value is `false`. Available in API version 48.0 and later.
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`
retryMessages	BotMessage[]	In Conversation Repair, the messages assigned to repair attempts. Available in API version 48.0 and later.
sourceVariableName	string	Name of the source VariableName used in the variable operation. (Available in API version 47.0 and later.)
sourceVariableType	ConversationVariableType (enumeration of type string)	This name defines the data type of VariableName used in the variable operation. (Available in API version 47.0 and later.) Valid values are: `ConversationVariable` `ContextVariable`
type	BotVariableOperationType (enumeration of type string)	Required. 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`

ConversationDefinitionNlpProvider

Defines the natural language service that is used for the language assigned to a bot version. Available in API version 49.0 and later.

Field Name	Field Type	Description
language	Language	Required. The language assigned to a bot version.
nlpProviderName	string	If nlpProviderType is EinsteinAI, this field is blank. If Apex, this field holds the Apex class name of the service.
nlpProviderType	ConversationDefinitionNlpProviderType (enumeration of type string)	Required. Default value is `EinsteinAi`. Valid values are: `EinsteinAi` `Apex`

ConversationRecordLookup

Information related to the linked conversation. Currently only works on Lightning Knowledge. Available in API version 46.0 and later.

Field Name	Field Type	Description
lookupFields	ConversationRecordLookupField []	Definition of the fields that are used for this lookup.
maxLookupResults	int	Required. The maximum numbers of records to return (1-3).
SObjectType	string	Required. Specifies the SObjectType of the ID stored in a bot variable.
sourceVariableName	string	Required. The input for this lookup operation.
sourceVariableType	ConversationVariableType (enumeration of type string)	Required. Type of the target used in the variable operation. Valid values are: `ConversationVariable` `ContextVariable`
targetVariableName	string	Required. The variable that holds the results of this lookup.

ConversationRecordLookupField

The fields used in a conversation record lookup. Available in API version 46.0 and later.

Field Name	Field Type	Description
fieldName	string	Required. Defines the field names used in the Conversation Lookup function.

ConversationSystemDialog

A system function assigned to a dialog. Available in API version 48.0 and later.

Field Name	Field Type	Description
dialog	string	The dialog name triggered when this system event fires.
type	ConversationSystemDialogType (enumeration of type string)	The type of system event. Required. Valid values are: `TransferFailed`

ConversationSystemMessage

System messages that represent an action for a Bot Step, such as transferring to an agent or ending a chat. Available in API version 46.0 and later.

Field Name	Field Type	Description
systemMessageMappings	ConversationSystemMessageMapping	Defines the type of system message to be sent.
type	ConversationSystemMessageType (enumeration of type string)	Required. This field defines the values available for a system message. Valid values are: `Transfer` `EndChat`

ConversationSystemMessageMapping

List of mappings that indicate additional information provided for the system message. Available in API version 46.0 and later.

Field Name	Field Type	Description
mappingType	ConversationMappingType (enumeration of type string)	Required. Defines the type of mapping used in the record. Valid values are `Input` and `Output`.
parameterType	ConversationSystemMessageParamType (enumeration of type string)	Required. Defines the type of parameter the value is mapped to. Valid value is `Transfer`.
variableName	string	Required. Name of the variable that contains the value passed to the system message.

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
collectionType	ConversationVariableCollectionType (enumeration of type string)	This field defines whether a variable is designated as a List Variable. Valid value is `List`.
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`
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.
label	string	Required. Label that identifies a variable throughout the Salesforce user interface.
SObjectType	string	Specifies the SObjectType of the ID stored in a bot variable. Valid values are: `BotDefinition` `Queue`

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.