将自定义消息传递组件添加到第三方消息传递渠道

何时使用自定义消息传递组件

当您通过原有 Salesforce 聊天部署或第三方消息传递渠道（例如 WhatsApp、Apple Messages for Business、Facebook Messenger 或 LINE）为客户提供服务，并且您希望客服人员返回丰富的交互式组件时，请使用自定义消息传递组件。

可自定义的消息传递表面保留了现成的消息传递响应格式（MessagingChoices、MessagingChoicesWithImages、MessagingRichLink和MessagingTimePicker），并允许您在它们的基础上添加新组件。

备注 如果您正在构建增强聊天 v2 (ECv2) 体验，请改用自定义 Lightning 类型。如果您正在构建完全外部的 Web 客户端，请使用自定义连接。

先决条件

• Service Cloud 消息传递渠道：在设置可自定义的消息传递连接之前，请为原有聊天或第三方渠道配置适当的 Service Cloud 消息传递渠道。
• 元数据 API 版本：使用版本 66.0 或更高版本进行检索和部署。
• 现有客服人员：使用基于文件的消息传递连接(SurfaceAction__Messaging)的 Agentforce 客服人员。
• 消息传递组件：已部署的消息传递组件（例如表单），您可以在响应格式中引用其 ID 或开发人员姓名。

工作原理

默认消息传递表面作为基于文件的表面 (SurfaceAction__Messaging) 提供，并附带四种现成的响应格式。要添加消息传递组件，使用引用相同四种回复格式以及新自定义格式的可自定义AiSurface替换基于文件的表面。

部署后，客服人员会将现成的响应格式用于选择、富链接和时间选择器，并在描述和说明与客户的请求匹配时选择自定义格式。

重要 请勿删除或编辑可自定义表面定义中列出的四种现成的响应格式。您可以添加新的回复格式，但不能修改现有的回复格式。

设置自定义消息传递组件

使用此结构组织元数据文件，然后完成以下步骤。

metadataToDeploy/
├── package.xml
├── aiResponseFormats/
│   └── Messaging_Form_Messaging_Component.aiResponseFormat
├── aiSurfaces/
│   └── {CustomMessagingSurface}.aiSurface
└── genAiPlannerBundles/
    └── {YourAgentDevName}.genAiPlannerBundle

步骤 1：检索客服人员的 GenAiPlannerBundle

通过元数据 API 检索客服人员的GenAiPlannerBundle。使用此package.xml进行检索。

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>*</members>
        <name>GenAiPlannerBundle</name>
    </types>
    <version>66.0</version>
</Package>

检索会返回客服人员的GenAiPlannerBundle。

metadataToDeploy/
└── genAiPlannerBundles/
    └── {YourAgentDevName}.genAiPlannerBundle

步骤 2：替换基于文件的消息传递表面

在GenAiPlannerBundle中，查找surface值为 SurfaceAction__Messaging 的plannerSurfaces条目。将surface更改为可自定义消息传递表面的唯一开发人员名称（例如，CustomMessagingSurface）。将surfaceType设置为Messaging。

<?xml version="1.0" encoding="UTF-8"?>
<GenAiPlannerBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <!-- Other agent configuration -->

    <plannerSurfaces>
        <adaptiveResponseAllowed>true</adaptiveResponseAllowed>
        <callRecordingAllowed>false</callRecordingAllowed>
        <surface>CustomMessagingSurface</surface>
        <surfaceType>Messaging</surfaceType>
    </plannerSurfaces>
</GenAiPlannerBundle>

此更改会分离基于文件的消息传递表面，并在原位附加可自定义的消息传递表面。

步骤 3：创建可自定义消息传递表面

在部署捆绑包中创建 aiSurfaces 文件夹。在其中，创建名为 {the_unique_dev_name_from_step_2}.aiSurface 的文件。文件的开发人员姓名必须与您在步骤 2 中设置的surface值相匹配。

可自定义表面必须包括所有四种现成的消息传递响应格式，以便标准消息传递行为继续工作。

<?xml version="1.0" encoding="UTF-8"?>
<AiSurface xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>Customizable Messaging connection</description>
    <instructions>
        <instruction>Do not use any of the SURFACE_ACTION__* response formats when none of the instructions below are met.</instruction>
        <sortOrder>1</sortOrder>
    </instructions>
    <instructions>
        <instruction>Do not use the below instructions when the response contains more than 10 choices.</instruction>
        <sortOrder>2</sortOrder>
    </instructions>
    <instructions>
        <instruction>Do not use any of the SURFACE_ACTION__Messaging* type formatting when the response contains only a single, text-only choice and does not include images or URLs.</instruction>
        <sortOrder>3</sortOrder>
    </instructions>
    <masterLabel>Messaging</masterLabel>
    <responseFormats>
        <enabled>true</enabled>
        <responseFormat>SurfaceAction__MessagingChoices</responseFormat>
    </responseFormats>
    <responseFormats>
        <enabled>true</enabled>
        <responseFormat>SurfaceAction__MessagingChoicesWithImages</responseFormat>
    </responseFormats>
    <responseFormats>
        <enabled>true</enabled>
        <responseFormat>SurfaceAction__MessagingRichLink</responseFormat>
    </responseFormats>
    <responseFormats>
        <enabled>true</enabled>
        <responseFormat>SurfaceAction__MessagingTimePicker</responseFormat>
    </responseFormats>
    <source>SurfaceAction__Messaging</source>
    <surfaceType>Messaging</surfaceType>
</AiSurface>

对于您想要客服人员使用的每个自定义消息传递组件，添加引用自定义AiResponseFormat开发人员姓名的responseFormats条目。

<responseFormats>
    <enabled>true</enabled>
    <responseFormat>Messaging_Form_Messaging_Component</responseFormat>
</responseFormats>

步骤 4：创建自定义 AiResponseFormat

创建aiResponseFormats文件夹。在其中，为每个自定义消息传递组件创建一个名为 {FormatDevName}.aiResponseFormat 的文件。

此示例定义了表单消息传递组件。使用MessageDefinition模板模式，input字段按开发人员姓名（或 ID）引用已部署的消息传递组件。将input_strategy设置为 use_template，以便客服人员填充模板，而不是生成原始 JSON。

<?xml version="1.0" encoding="UTF-8"?>
<AiResponseFormat xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>A response action. Use this when the user wants to create a case. The user is presented with rich UI.</description>
    <input>{"template":{"messageType":"FormMessage","id":"{{ uuid4() }}","form":{"formatType":"MessageDefinition","messageDefinitionNameOrId":"Create_Case_Form"}},"input_strategy":"use_template"}</input>
    <instructions>
        <instruction>Always use this response format to create a case.</instruction>
        <sortOrder>1</sortOrder>
    </instructions>
    <masterLabel>Messaging Form Messaging Component</masterLabel>
</AiResponseFormat>

表格模板模式

将此模板模式用于表单消息传递组件。AiResponseFormat 上的 input 字段必须是单行 JSON 编码字符串。此处显示的扩展版本仅供阅读。

{
  "template": {
    "messageType": "FormMessage",
    "id": "{{ uuid4() }}",
    "form": {
      "formatType": "MessageDefinition",
      "messageDefinitionNameOrId": "Create_Case_Form"
    }
  },
  "input_strategy": "use_template"
}

步骤 5：创建 package.xml 文件

在部署捆绑包的根目录创建package.xml文件，声明所有三种元数据类型。

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>*</members>
        <name>AiResponseFormat</name>
    </types>
    <types>
        <members>*</members>
        <name>AiSurface</name>
    </types>
    <types>
        <members>*</members>
        <name>GenAiPlannerBundle</name>
    </types>
    <version>66.0</version>
</Package>

步骤 6：部署

使用 Salesforce CLI 部署元数据。

sf project deploy start --manifest metadataToDeploy/package.xml

您也可以使用首选元数据 API 工具进行部署。如果增量部署，请在AiSurface实体之前部署AiResponseFormat实体，因为表面引用响应格式。

另请参阅

• 消息传递组件类型和格式
• 增强 Web 聊天
• 设置自定义连接
• 自定义连接的响应格式示例