Adicionar componentes de mensagens personalizados a um canal de mensagens de terceiros

Quando usar componentes de mensagens personalizados

Use componentes de mensagens personalizados ao atender clientes por meio de implantações de chat do Salesforce legadas ou canais de mensagens de terceiros, como WhatsApp, Apple Messages for Business, Facebook Messenger ou LINE, e você deseja que o agente retorne componentes avançados e interativos.

A superfície personalizável do Messaging preserva os formatos de resposta do Messaging prontos para uso (MessagingChoices, MessagingChoicesWithImages, MessagingRichLink e MessagingTimePicker) e permite adicionar novos componentes.

Nota Se você estiver criando uma experiência do Chat v2 (ECv2), use Tipos personalizados do Lightning. Se você estiver criando um cliente da Web totalmente externo, use Conexões personalizadas.

Pré-requisitos

• Canal de mensagens do Service Cloud: Configure o canal de mensagens do Service Cloud apropriado para chat legado ou seu canal de terceiros antes de configurar a conexão de mensagens personalizável.
• Versão da API de metadados: Use a versão 66.0 ou posterior para recuperação e implantação.
• Agente existente: Um agente Agentforce que usa a conexão de mensagens baseada em arquivo (SurfaceAction__Messaging).
• Componente de mensagens: Um componente de mensagens implantado (como um formulário) cujo ID ou nome de desenvolvedor você pode referenciar no formato de resposta.

Como funciona

A superfície padrão do Messaging é fornecida como uma superfície baseada em arquivo (SurfaceAction__Messaging) que é enviada com quatro formatos de resposta prontos para uso. Para adicionar um componente de mensagens, substitua a superfície baseada em arquivo por um AiSurface personalizável que faça referência aos mesmos quatro formatos de resposta e ao novo formato personalizado.

Após a implantação, o agente usa os formatos de resposta prontos para uso para opções, links avançados e seletores de horário e seleciona seu formato personalizado quando sua descrição e instruções correspondem à solicitação do cliente.

Importante Não remova nem edite os quatro formatos de resposta prontos para uso listados na definição de superfície personalizável. Você pode adicionar novos formatos de resposta, mas não modificar os existentes.

Configurar componentes de mensagens personalizados

Organize seus arquivos de metadados usando essa estrutura e conclua as etapas a seguir.

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

Etapa 1: recuperar o GenAiPlannerBundle do agente

Recupere os GenAiPlannerBundle do seu agente por meio da API de metadados. Use este package.xml para a recuperação.

<?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>

A recuperação retorna a GenAiPlannerBundle para seu agente.

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

Etapa 2: substituir a área de mensagens baseada em arquivo

Em seu GenAiPlannerBundle, localize a entrada de plannerSurfaces cujo valor de surface seja SurfaceAction__Messaging. Altere o surface para um nome de desenvolvedor exclusivo para sua área de mensagens personalizável (por exemplo, CustomMessagingSurface). Deixe o surfaceType definido como 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>

Essa alteração desanexa a superfície de mensagens baseada em arquivo e anexa sua superfície de mensagens personalizável no lugar.

Etapa 3: criar a superfície de mensagens personalizável

Crie uma pasta de aiSurfaces em seu pacote de implementação. Dentro dele, crie um arquivo chamado {the_unique_dev_name_from_step_2}.aiSurface. O nome do desenvolvedor do arquivo deve corresponder ao valor de surface definido na Etapa 2.

A superfície personalizável deve incluir todos os quatro formatos de resposta de mensagens prontos para uso para que o comportamento de mensagens padrão continue funcionando.

<?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>

Para cada componente de mensagens personalizado que você deseja que o agente use, adicione uma entrada de responseFormats que faça referência ao nome do desenvolvedor do seu AiResponseFormat personalizado.

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

Etapa 4: criar o AiResponseFormat personalizado

Crie uma pasta de aiResponseFormats. Dentro dele, crie um arquivo chamado {FormatDevName}.aiResponseFormat para cada componente de mensagens personalizado.

Este exemplo define um componente de mensagens de formulário. O campo input faz referência a um componente de mensagens implementado por nome do desenvolvedor (ou ID) usando o esquema de modelo de MessageDefinition. Defina input_strategy como use_template para que o agente preencha o modelo em vez de gerar JSON bruto.

<?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>

Esquema de modelo de formulário

Use esse esquema de modelo para componentes de mensagens de formulário. O campo input na AiResponseFormat deve ser uma string de linha única codificada em JSON. A versão expandida aqui é mostrada apenas para legibilidade.

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

Etapa 5: criar o arquivo package.xml

Crie um arquivo package.xml na raiz do pacote de implementação que declare todos os três tipos de metadados.

<?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>

Etapa 6: Implementar

Implemente os metadados com o Salesforce CLI.

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

Você também pode implementar com sua ferramenta de API de metadados preferida. Se você implantar incrementalmente, implante entidades de AiResponseFormat antes de entidades de AiSurface, pois a exibição faz referência aos formatos de resposta.

Consulte também

• Tipos e formatos de componente de Mensagens
• Chat da Web aprimorado
• Configurar uma conexão personalizada
• Exemplos de formato de resposta para conexões personalizadas