ConversationMessageDefinition Metadata Type in SFDX

Architectural Overview#

In legacy Live Agent chat, interactions were limited to plain text. With Enhanced Messaging (Messaging for In-App and Web, Enhanced WhatsApp, Facebook Messenger, Apple Messages for Business, and BYOC), Service Cloud supports structured, interactive Messaging Components.

The ConversationMessageDefinition metadata type is the declarative XML representation of a Messaging Component. A single ConversationMessageDefinition can define an interactive payload (type = ChoicesQuestion, TimeSelectorQuestion, FormRequest, Link, StaticContent, or ExternalTemplate) along with channel-specific layout adaptation (messageLayouts). At runtime, Omni-Channel Flows, Service Agents, or Agentforce / Einstein Bots invoke the ConversationMessageDefinition and Salesforce automatically renders the appropriate native widget for the customer’s channel (for example, an Apple Pay / Time Picker bubble on iOS or a WhatsApp Interactive List on WhatsApp).

SFDX Directory and File Suffix#

Key Metadata Fields#

ConversationMessageDefinition combines input parameters, constant values, interactive options, and multi-channel layout definitions.

Declarative XML Example#

Below is a production Order_Status_Rich_Link.conversationMessageDefinition-meta.xml defining a Link Messaging Component that accepts a dynamic TrackingUrl parameter from a Flow and renders both a Rich Link card (for In-App & Web and WhatsApp) and a plain-text SMS fallback.

<?xml version="1.0" encoding="UTF-8"?>
<ConversationMessageDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
    <constants>
        <constantType>Title</constantType>
        <dataType>Text</dataType>
        <name>LinkTitleConstant</name>
        <textValue>Track Your Shipment Live</textValue>
    </constants>
    <constants>
        <constantType>Image</constantType>
        <dataType>ImageAsset</dataType>
        <imageAssetValue>Order_Tracking_Card_Banner</imageAssetValue>
        <name>BannerImageConstant</name>
    </constants>
    <description>Sends an interactive rich link card with live carrier tracking URL and SMS fallback.</description>
    <label>Order Status Rich Link</label>
    <messageLayouts>
        <formatType>RichLink</formatType>
        <layoutItems>
            <collectionType>None</collectionType>
            <name>linkItem</name>
            <value>
                <CleanName>RichLinkPayload</CleanName>
                <constantValue>LinkTitleConstant</constantValue>
            </value>
        </layoutItems>
        <messageType>StaticContent</messageType>
    </messageLayouts>
    <messageLayouts>
        <formatType>Text</formatType>
        <layoutItems>
            <collectionType>None</collectionType>
            <name>textFallback</name>
            <value>
                <formulaTemplate>Track your shipment here: {!$Parameters.TrackingUrl}</formulaTemplate>
                <type>FormulaTemplate</type>
            </value>
        </layoutItems>
        <messageType>StaticContent</messageType>
    </messageLayouts>
    <parameters>
        <dataType>Url</dataType>
        <description>Dynamic carrier tracking URL passed from the Order Lookup Flow.</description>
        <isList>false</isList>
        <isRequired>true</isRequired>
        <label>Tracking URL</label>
        <name>TrackingUrl</name>
    </parameters>
    <type>Link</type>
</ConversationMessageDefinition>

package.xml Manifest#

Include any referenced ContentAsset images and ConversationMessageDefinitionTranslation files when deploying ConversationMessageDefinition:

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

Querying via SOQL and SFDX CLI#

You can query ConversationMessageDefinition via Tooling API / SOQL to audit active Messaging Components across your org.

1. Query Messaging Components by Type#

SELECT Id, DeveloperName, MasterLabel, Type, Description, ManageableState, LastModifiedDate
FROM ConversationMessageDefinition
ORDER BY Type, DeveloperName ASC

2. SFDX CLI Retrieve and Deploy Commands#

# Retrieve a specific ConversationMessageDefinition
sf project retrieve start --metadata ConversationMessageDefinition:Order_Status_Rich_Link

# Deploy all ConversationMessageDefinition files
sf project deploy start --metadata ConversationMessageDefinition

Architect Best Practices and Gotchas#

• Deploy ContentAsset Dependencies First: Whenever a <constants> block has dataType = ImageAsset, the target ContentAsset must be included in the package or already exist in the org.
• Flow Action Coupling: If a ConversationMessageDefinition is referenced by a Send Conversation Messages action inside an active Flow, you cannot delete parameters or change parameter dataType values without first updating or deactivating the referencing Flow version.

Frequently asked questions

What UI feature in Setup corresponds to ConversationMessageDefinition?

ConversationMessageDefinition corresponds to Messaging Components in Service Cloud Setup, which let agents, Omni-Channel Flows, and bots send interactive questions, forms, payment requests, and rich links in Enhanced Messaging sessions.

Where are ConversationMessageDefinition files stored in SFDX?

They are stored in force-app/main/default/conversationMessageDefinitions/ with the file suffix .conversationMessageDefinition-meta.xml.

What message types does ConversationMessageDefinition support?

It supports StaticContent, Link, ChoicesQuestion (Quick Replies and List Selectors), TimeSelectorQuestion, FormRequest, AuthenticationRequest, PaymentRequest, and ExternalTemplate (such as WhatsApp approved templates).

How are dynamic variables injected into a ConversationMessageDefinition at runtime?

You define primitive or sObject parameters inside the constants and parameters blocks of the message definition and pass values from a Flow Send Conversation Messages action or an Einstein Bot.