Prompt | Metadata API Developer Guide

Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

Important

File Suffix and Directory Location

Prompt components have the suffix prompt and are stored in the prompts folder.

Version

Prompt components are available in API version 46.0 and later.

Special Access Rules

To add, edit, and manage prompts and walkthroughs as an admin, the Modify All Data or Customize Application permission is required.
To add, edit, and manage prompts and walkthroughs as a user who isn’t an admin, the Manage Prompts and View All Profiles permission is required.
To have more than three custom walkthroughs active at a time, purchase the Enablement add-on license and assign the Use Custom Walkthroughs permission set, which uses the Walkthroughs permission set license.

Prompts and Walkthroughs in Managed Packages

For considerations about including in-app guidance in a managed package, see Guidelines for In-App Guidance in Managed Packages in Salesforce Help.

For more information about creating managed packages, see Create a First-Generation Managed Package.

Unmanaged packages must contain a namespace prefix. For more information, see Register a Namespace for a First-Generation Managed Packages and What happens to my namespace prefix when I install a package?.

Fields

Field Name	Field Type	Description
masterLabel	string	Required. The label. Maximum of 80 characters.
promptVersions	PromptVersion[]	A list of in-app guidance entries. Each entry represents a different prompt or walkthrough.

PromptVersion

A list of in-app guidance entries. Each entry represents a different prompt or walkthrough.

Field Name	Field Type	Description
actionButtonLabel	string	Label for the action button or link. Maximum of 25 characters. For walkthroughs, this field can only be specified on the last step.
actionButtonLink	string	URL for the action button or link. Maximum of 1,000 characters. You can’t use the `GROUP BY` option in a SOQL query for this field. For walkthroughs, this field can only be specified on the last step.
body	string	Required. Body content. For floating prompts, there’s a maximum of 240 characters. For docked prompts, there’s a maximum of 4000 characters. Because the docked prompt has a rich text editor, the maximum characters refer to HTML markup, not readable text.
customApplication	string	Internal use only. No data is populated for this field.
delayDays	int	Required if recurrences are scheduled. Number of days in between occurrences. For walkthroughs, this field can only be specified on the first step.
description	string	Description. Maximum of 255 characters.
dismissButtonLabel	string	Label for the dismiss button of a floating prompt. Maximum of 15 characters.
displayPosition	PromptDisplayPosition (enumeration of type string)	Indicates the position of the floating prompt on the page. Valid values are: `BottomCenter` `BottomLeft` `BottomRight` `TopCenter` `TopLeft` `TopRight`
displayType	PromptDisplayType (enumeration of type string)	Required. Indicates the type of prompt. Valid values are: `DockedComposer`, which is the docked prompt `FloatingPanel`, which is the floating prompt `Targeted`, which is the targeted prompt. Available in API version 52.0 and later.
elementRelativePosition	PromptElementRelativePosition (enumeration of type string)	Indicates the location of the prompt relative to the element. Available in API version 52.0 and later. Valid values are: `BottomCenter` `BottomLeft` `BottomRight` `LeftBottom` `LeftCenter` `LeftTop` `RightBottom` `RightCenter` `RightTop` `TopCenter` `TopLeft` `TopRight`
endDate	date	Indicates the date to stop showing the in-app guidance. For walkthroughs, this field can only be specified on the first step.
header	string	Label for the header of the docked prompt. This is the label contained in the window’s browser bar. Maximum of 36 characters.
image	string	The developer name of the contentAsset that holds the image. You can specify this field or the `imageLink` field, but not both.
imageAltText	string	Indicates the alt text of an image, which helps make images accessible. Required if `imageLocation`, `imageLink`, or `image` is specified.
imageLink	string	The URL for a prompt’s image. You can specify this field or the image field, but not both. Available in API version 53.0 and later.
imageLocation	picklist	Indicates the location of the image in relation to the body text. Required if `image`, `imageLink`, or `imageAltText` is specified. Valid values are: `Top` `Bottom` `Right`, which is for floating prompts only `Left`, which is for floating prompts only
indexWithIsPublished	string	Used by Salesforce for efficient querying.
indexWithoutIsPublished	string	Used by Salesforce for efficient querying.
isPublished	boolean	Indicates if active `true` or not `false`.
masterLabel	string	Required. The label.
publishedByUser	string	Internal use only. No data is populated for this field.
publishedDate	date	Indicates the date the in-app guidance was activated. If installed from a package, this is the date when the package was installed. For walkthroughs, this field can only be specified on the first step.
referenceElementContext	textarea	Used by Salesforce to identify the element that the targeted prompt is associated with. Available in API version 52.0 and later.
shouldDisplayActionButton	boolean	Indicates if an action button or link is included `true` or not `false`.
shouldIgnoreGlobalDelay	boolean	Indicates if the in-app guidance ignores the global time delay and instead shows on page load `true` or not `false`. This field is available in API version 48.0 and later.
startDate	date	Indicates the date to start showing the in-app guidance. For walkthroughs, this field can only be specified on the first step. In API version 48.0 and earlier, this field is required.
stepNumber	int	Required for walkthroughs only. Indicates the number of the last step the user viewed or interacted with in a walkthrough. Maximum of 10 steps. Numbers must be consecutive without repeated or skipped numbers. Available in API version 49.0 and later.
targetAppDeveloperName	string	The app’s developer name where the in-app guidance appears. Deprecated in API version 51.0 and later.
targetAppNamespacePrefix	string	The app’s namespace prefix where the in-app guidance appears. Must match the target app’s `NamespacePrefix` in the org that the package is being installed into. Maximum of 15 characters. Deprecated in API version 51.0 and later.
targetPageKey1	string	Required. Used by Salesforce to identity the prompt’s page location along with `targetPageKey2`, `targetPageKey3`, `targetPageKey4`, and `targetPageType`.
targetPageKey2	string	Used by Salesforce to identity the prompt’s page location along with `targetPageKey1`, `targetPageKey3`, `targetPageKey4`, and `targetPageType`.
targetPageKey3	string	Used by Salesforce to identify the prompt’s page location along with `targetPageKey1`, `targetPageKey2`, `targetPageKey4`, and `targetPageType`.
targetPageKey4	string	Used by Salesforce to identify the prompt’s page location along with `targetPageKey1`, `targetPageKey2`, `targetPageKey3`, and `targetPageType`. This field is available in API version 53.0 and later.
targetPageType	string	Required. Used by Salesforce to identity the page location along with `targetPageKey1`, `targetPageKey2`, `targetPageKey3`, and `targetPageKey4`.
targetRecordType	string	Used by Salesforce to determine if in-app guidance is specific to a record type. This field is available in API version 53.0 and later.
themeColor	PromptThemeColor (enumeration of type string)	Indicates which custom theme color is applied to in-app guidance. Required if themeSaturation is specified. Specify on the first step of the walkthrough to apply to the entire walkthrough. Valid values are: `Theme1`, which is derived from the current brand color `Theme2`, which is derived from the current page background color `Theme3`, which is derived from the current global header color `Theme4`, which is derived from the current app theme color
themeSaturation	PromptThemeSaturation (enumeration of type string)	Indicates which color value, or saturation, is applied to in-app guidance that has a custom theme color applied. Required if themeColor is specified. Specify on the first step of the walkthrough to apply to the entire walkthrough. Valid values are: `Dark` `Light`
timesToDisplay	int	Required if recurrences are scheduled. Maximum number of times to display the in-app guidance (that is, the number of occurrences). Salesforce detects if the user interacts with (or ignores) the in-app guidance to determine if we should show the in-app guidance again or cancel scheduled recurrences. This might run counter to the number of occurrences scheduled. Maximum value of 30. For walkthroughs, this field can only be specified on the first step.
title	string	Required. The label for the title. Maximum of 36 characters.
uiFormulaRule	UiFormulaRule	A set of one or more permission filters that define the conditions under which the in-app guidance displays on the page. If the rule evaluates to `true`, the in-app guidance displays on the page. If `false`, it doesn't display. If this field is `null`, the in-app guidance displays by default.
userAccess	PromptUserAccess (enumeration of type string)	Indicates which permissions can see the in-app guidance. Valid values are: `Everyone`, which indicates that there’s no permission restrictions `SpecificPermissions`, which indicates that only users with all the specific user permissions specified can see the in-app guidance In API version 48.0 and earlier, this field is required.
userProfileAccess	PromptUserProfileAccess (enumeration of type string)	Indicates which profiles can see the in-app guidance. This field is available in API version 48.0 and later. Valid values are: `Everyone`, which indicates that there are no profile restrictions `SpecificProfiles`, which indicates that users with any of the specified user profiles can see the in-app guidance
versionNumber	int	Required. The number remains `1` since multiple versions aren’t saved in the org.
videoLink	string	The URL for the video in a docked prompt. Maximum of 1,000 characters. You can specify this field or the `image` field, but not both. This field is available in API version 48.0 and later. To find the embed code for a video, follow the instructions from the video host website. Usually the steps can be found by searching for the name of the website and “embed video.” For example, here’s what the embed code looks like for YouTube: `<iframe width="560" height="315" src="https://www.youtube.com/embed/di6iwHhrH6s" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>` Then, you would enter the URL found in the `src` attribute. For the example used, enter `https://www.youtube.com/embed/di6iwHhrH6s`.

UiFormulaRule

A set of one or more filters that define the conditions under which a prompt displays on a Lightning page.

Field Name	Field Type	Description
booleanFilter	string	Specifies the AND filter condition.
criteria	UiFormulaCriterion[]	List of one or more filters that, when evaluated, determine visibility.

UiFormulaCriterion

A single filter that, when evaluated, helps define visibility on a Lightning page.

Field Name	Field Type	Description
leftValue	string	Required. The field upon which the filter is based. Only standard and custom permissions can be included. You can use these expressions in the leftValue field when setting filters for visibility. `{!$Permission.CustomPermission.permissionName}`—Use this expression to control visibility based on the custom permissions of the user viewing the Lightning page. Supported for app, Home, and record pages only. `{!$Permission.StandardPermission.permissionName}`—Use this expression to control visibility based on the standard permissions of the user viewing the Lightning page. Supported for app, Home, and record pages only. `{!ENCODED:{!ID:$User.Profile.Key}}`—Use this expression to control visibility based on the custom or standard profile of the user viewing the Lightning page. Available in API Version 48.0 and later.
operator	string	Required. Defines the operator used to filter the data. Valid value is `EQUAL`.
rightValue	string	Specifies if you want to evaluate the visibility for permissions or the name of the profile. For permissions, use `true`. For profiles, use the name of the profile. Available in API Version 48.0 and later. For example, `Standard`or `custom_regionalsales`.

Declarative Metadata Sample Definition

The following is an example of a Prompt component.

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

Wildcard Support in the Manifest File

This metadata type supports 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.