ConversationChannelDefinition Metadata Type in SFDX

Architectural Overview#

Salesforce Bring Your Own Channel (BYOC) for Messaging and CCaaS allows enterprises and ISV partners to integrate any external messaging platform (such as regional messaging apps, proprietary mobile chat, or custom CCaaS routers) directly into the native Service Cloud Console and Omni-Channel routing engine (MessagingSession and ConversationEntry).

The ConversationChannelDefinition metadata type is the technical bridge of the BYOC architecture. It connects four foundational pillars into a unified messaging channel definition:

1. Partner Identity: References a ConversationVendorInfo metadata record (conversationVendorInfo).
2. Inbound Authentication: Links the ConnectedApp (connectedAppType) used by the external vendor to call Salesforce’s Interaction Service API (/api/v1/interactions).
3. Outbound Delivery: Binds a NamedCredential (namedCredential) or Platform Event channel (customEventType / customPlatformEvent) to push agent replies, typing indicators, and routing requests back to the external messaging gateway.
4. Channel Capabilities: Declares supported rich content capabilities (isTypingIndicatorDisabled, areReadReceiptsDisabled, maxFileSize, supported file extensions).

SFDX Directory and File Suffix#

Key Metadata Fields#

ConversationChannelDefinition configures the authentication, event transport, and rich media capabilities of a custom conversation channel.

Declarative XML Example#

Below is a complete Line_Enterprise_Channel.conversationChannelDefinition-meta.xml configuring a BYOC Messaging integration where Salesforce Omni-Channel owns routing (routingOwner = Salesforce) and outbound messages are emitted via a custom Platform Event (Vendor_Outbound_Message__e).

<?xml version="1.0" encoding="UTF-8"?>
<ConversationChannelDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
    <areReadReceiptsDisabled>false</areReadReceiptsDisabled>
    <capabilitiesSupportsCustomChannelParameters>true</capabilitiesSupportsCustomChannelParameters>
    <connectedAppType>Line_BYOC_Interaction_ConnectedApp</connectedAppType>
    <consentOwner>Partner</consentOwner>
    <conversationVendorInfo>Line_Messaging_Vendor</conversationVendorInfo>
    <customEventType>Line_Outbound_Event_Channel</customEventType>
    <customPlatformEvent>Vendor_Outbound_Message__e</customPlatformEvent>
    <isTypingIndicatorDisabled>false</isTypingIndicatorDisabled>
    <masterLabel>LINE Enterprise Messaging Channel</masterLabel>
    <namedCredential>Line_Messaging_Gateway_API</namedCredential>
    <routingOwner>Salesforce</routingOwner>
</ConversationChannelDefinition>

package.xml Manifest#

Always bundle ConversationChannelDefinition with its required ConversationVendorInfo, ConnectedApp, PlatformEventChannel, and CustomObject (__e) dependencies:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Line_Enterprise_Channel</members>
        <name>ConversationChannelDefinition</name>
    </types>
    <types>
        <members>Line_Messaging_Vendor</members>
        <name>ConversationVendorInfo</name>
    </types>
    <types>
        <members>Line_Outbound_Event_Channel</members>
        <name>PlatformEventChannel</name>
    </types>
    <types>
        <members>Vendor_Outbound_Message__e</members>
        <name>CustomObject</name>
    </types>
    <version>68.0</version>
</Package>

Querying via SOQL and SFDX CLI#

You can query ConversationChannelDefinition directly in SOQL or Tooling API to inspect configured BYOC adapters and routing ownership.

1. Query Configured BYOC Channel Definitions via SOQL#

SELECT Id, DeveloperName, MasterLabel, RoutingOwner, ConsentOwner,
       ConversationVendorInfoId, CustomPlatformEvent, CreatedDate
FROM ConversationChannelDefinition
ORDER BY DeveloperName ASC

2. SFDX CLI Retrieve and Deploy Commands#

# Retrieve a specific ConversationChannelDefinition
sf project retrieve start --metadata ConversationChannelDefinition:Line_Enterprise_Channel

# Deploy the BYOC channel definition
sf project deploy start --metadata ConversationChannelDefinition:Line_Enterprise_Channel

Architect Best Practices and Gotchas#

• routingOwner Architectural Choice (Salesforce vs. Partner):
  • Choose Salesforce (BYOC for Messaging) when you want Salesforce Omni-Channel Flows, Queues, Skills, and Einstein Bots / Agentforce Agents to control routing and agent assignment.
  • Choose Partner (BYOC for CCaaS) when an external contact center router (such as Genesys, Amazon Connect, or Nice CXone) controls agent state and pushes work assignments into Salesforce via the Interaction Service API.
• Connected App OAuth Scope: The ConnectedApp referenced in <connectedAppType> must include the chatbot_api and sfap_api (or Interaction Service) OAuth scopes and use the Client Credentials or JWT Bearer flow for machine-to-machine reliability.

Frequently asked questions

What is ConversationChannelDefinition used for in Service Cloud?

ConversationChannelDefinition defines the channel adapter configuration for Bring Your Own Channel (BYOC) for Messaging and CCaaS, allowing third-party messaging networks (such as LINE, KakaoTalk, or custom chat apps) to route into Omni-Channel.

Where are ConversationChannelDefinition files stored in SFDX?

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

What metadata dependencies does ConversationChannelDefinition require?

It requires an active ConversationVendorInfo component, a ConnectedApp for inbound Interaction Service API calls, a NamedCredential for outbound webhooks, and a CustomPlatformEvent or PlatformEventChannel.

Can ConversationChannelDefinition be packaged by ISVs?

Yes. Messaging and CCaaS partners package ConversationChannelDefinition alongside ConversationVendorInfo in managed packages so customers can install turnkey third-party messaging channels.