Legacy Dialogflow CX Messenger

A integração do Messenger do Dialogflow CX antigo oferece uma caixa de diálogo de chat personalizável para o seu agente que pode ser incorporada no seu Website. A caixa de diálogo do chat é implementada como uma janela de diálogo que pode ser aberta e fechada pelo utilizador final. Quando aberto, a caixa de diálogo do chat aparece acima do conteúdo na parte inferior direita do ecrã.

Migrar para o Dialogflow CX Messenger mais recente

A versão mais recente do Dialogflow CX Messenger oferece autenticação para controlar o acesso a consultas do agente e mais opções de configuração da interface do utilizador. Recomendamos que todos os utilizadores da versão antiga migrem para a nova versão.

Se ativou a integração do Dialogflow CX Messenger antes de 29 de agosto de 2023, pode estar a usar a versão antiga. Para determinar se está a usar a versão antiga, examine o código HTML do Messenger incorporado no seu Website. Se vir o seguinte script, está a usar a versão antiga:

https://www.gstatic.com/dialogflow-console/fast/messenger-cx/bootstrap.js?v=1

Para migrar para a nova versão:

  1. Elimine todo o código do Messenger HTML, CSS e JavaScript do seu Website.
  2. Siga as instruções para a integração mais recente do Dialogflow CX Messenger.

Personalizações de HTML

Pode personalizar vários aspetos da forma como a caixa de diálogo do chat aparece e se comporta. O elemento HTML df-messenger tem os seguintes atributos:

Atributo Política de introdução Valor
agent-id Obrigatória ID do agente associado ao agente. Este campo é pré-preenchido com o ID do agente.
chat-icon Opcional Ícone usado para o botão de abertura da caixa de diálogo do chat. O ícone Agentes de conversação (Dialogflow CX) é o predefinido. Este campo tem de ser um URL público. O tamanho do ícone deve ser de 36 px por 36 px.
chat-title Obrigatória Título apresentado na parte superior da caixa de diálogo do chat. Este campo é pré-preenchido com o nome do agente.
df-cx Obrigatória Indica que a interação é com um agente do CX. Use "true" como valor.
expand Opcional Atributo booleano que define a caixa de diálogo do chat como aberta quando a página é carregada. Por predefinição, a caixa de diálogo de chat é fechada quando a página é carregada.
intent Opcional Um evento personalizado que é invocado quando a caixa de diálogo do chat é aberta. Pode usar um controlador de eventos que é chamado para este evento e produz a primeira mensagem do agente.
language-code Obrigatória Código do idioma predefinido para a primeira intenção. Este campo é pré-preenchido com o idioma predefinido do agente.
location Obrigatória A região do agente.
session-id Opcional Um ID da sessão. Se não for fornecido, a integração gera um ID exclusivo para cada diálogo de chat.
user-id Opcional Pode ser usado para acompanhar um utilizador em várias sessões. Pode transmitir o valor aos agentes conversacionais (Dialogflow CX) através do campo queryParams.payload.userId num pedido de deteção de intenção, e os agentes conversacionais (Dialogflow CX) fornecem-lhe este valor através do campo WebhookRequest.payload.userId.
wait-open Opcional Atributo booleano que atrasa o evento personalizado definido no atributo intent até que a caixa de diálogo seja efetivamente aberta.

Personalizações de CSS

Pode personalizar o estilo da caixa de diálogo do chat definindo variáveis CSS.

Podem ser fornecidas as seguintes variáveis de CSS:

Variável CSS Propriedade afetada
df-messenger-bot-message Cor de fundo do balão para mensagens do agente.
df-messenger-button-titlebar-color Cor do botão flutuante e da barra de título da caixa de diálogo do chat.
df-messenger-button-titlebar-font-color Cor do tipo de letra do título na barra de título.
df-messenger-chat-background-color Cor do fundo da caixa de diálogo de chat.
df-messenger-font-color Cor do tipo de letra para mensagens.
df-messenger-input-box-color Cor de fundo da caixa de introdução de texto.
df-messenger-input-font-color Cor do tipo de letra da caixa de introdução de texto.
df-messenger-input-placeholder-font-color Cor do tipo de letra do texto do marcador de posição na caixa de entrada de texto.
df-messenger-minimized-chat-close-icon-color Cor do ícone de fechar na vista de chat fechada.
df-messenger-send-icon Cor do ícone de envio na caixa de introdução de texto.
df-messenger-user-message Cor de fundo do balão para mensagens do utilizador.

Exemplo de código:

<style>
  df-messenger {
   --df-messenger-bot-message: #878fac;
   --df-messenger-button-titlebar-color: #df9b56;
   --df-messenger-chat-background-color: #fafafa;
   --df-messenger-font-color: white;
   --df-messenger-send-icon: #878fac;
   --df-messenger-user-message: #479b3d;
  }
</style>

As definições acima resultam no seguinte:

Captura de ecrã do Messenger

Eventos JavaScript

O Dialogflow Messenger aciona uma variedade de eventos para os quais pode criar ouvintes de eventos.

O alvo do evento destes eventos é o elemento df-messenger.

Para adicionar um ouvinte de eventos para o elemento df-messenger, adicione o seguinte código JavaScript, em que event-type é um dos nomes de eventos descritos abaixo:

const dfMessenger = document.querySelector('df-messenger');
dfMessenger.addEventListener('event-type', function (event) {
  // Handle event
  ...
});

São suportados os seguintes tipos de eventos:

df-accordion-clicked

Este evento ocorre quando um utilizador clica num elemento de acordeão. A estrutura do evento tem o seguinte aspeto:

element: {
  title: string,
  subtitle: string,
  image: {
    src: {rawUrl: string}
  },
  text: string
}

df-button-clicked

Este evento ocorre quando um utilizador clica num elemento de botão. A estrutura do evento tem o seguinte aspeto:

element: {
  icon: {
    type: string,
    color: string
  },
  text: string,
  link: string,
  event: EventInput,
  payload: {}
}

df-chip-clicked

Este evento ocorre quando um utilizador seleciona um chip de sugestão. A estrutura do evento tem o seguinte aspeto:

query: string // Text of the suggestion chip that was selected.

df-info-card-clicked

Este evento ocorre quando o utilizador final clica no item de informações na barra de título. A estrutura do evento tem o seguinte aspeto:

element: {
  title: string,
  image: {
    src: {rawUrl: string}
  },
  actionLink: string
}

df-list-element-clicked

Este evento ocorre quando um utilizador clica num artigo numa lista. A estrutura do evento tem o seguinte aspeto:

element: {
  title: string,
  subtitle: string,
  image: {
    src: {rawUrl}
  },
  event: {
    name: string
  },
  payload: {}
}

df-messenger-error

Este evento ocorre quando a API Dialogflow envia um código de estado de erro. A estrutura do evento tem o seguinte aspeto:

error: {
  "error": {
    "code": <error_code>,
    "message": <error_message>,
    "status": <error_status>
  }
}

df-messenger-loaded

Este evento é acionado quando o elemento df-messenger é totalmente carregado e inicializado.

df-request-sent

Este evento ocorre quando é feito um pedido à API Dialogflow. Este evento, juntamente com df-response-received, pode ser usado para monitorizar a latência dos pedidos. A estrutura do evento tem o seguinte aspeto:

requestBody: {
  "queryParams": {
    object(QueryParameters)
  },
  "queryInput": {
    object(QueryInput)
  },
  "inputAudio": string
}

df-response-received

Este evento ocorre quando é recebida uma resposta da API Dialogflow. A estrutura do evento tem o seguinte aspeto:

response: detectIntentResponse

df-user-input-entered

Este evento ocorre quando o utilizador final introduz uma consulta. A estrutura do evento tem o seguinte aspeto:

input: string // Text entered by user

Funções JavaScript

O elemento df-messenger fornece funções que pode chamar para afetar o respetivo comportamento.

renderCustomText

Esta função renderiza uma mensagem de texto simples, como se fosse proveniente de agentes conversacionais (Dialogflow CX) como resposta de texto simples.

Por exemplo:

const dfMessenger = document.querySelector('df-messenger');
dfMessenger.renderCustomText('Custom text');

renderCustomCard

Esta função renderiza um cartão personalizado, como se fosse proveniente do preenchimento de agentes conversacionais (Dialogflow CX). O formato da resposta de payload personalizado é definido na secção Preenchimento.

Por exemplo:

const dfMessenger = document.querySelector('df-messenger');
const payload = [
  {
    "type": "info",
    "title": "Info item title",
    "subtitle": "Info item subtitle",
    "image": {
      "src": {
        "rawUrl": "https://example.com/images/logo.png"
      }
    },
    "actionLink": "https://example.com"
  }];
dfMessenger.renderCustomCard(payload);

showMinChat

Esta função mostra uma versão mínima das listas de mensagens.

Por exemplo:

const dfMessenger = document.querySelector('df-messenger');
dfMessenger.showMinChat();

Fulfillment

Quando cria um processamento de pedidos, pode criar respostas de texto e conteúdos personalizados. As respostas de texto são usadas para respostas básicas do agente e os payloads personalizados são usados para respostas avançadas. O formato de payload personalizado para todos os tipos de respostas tem a seguinte estrutura básica:

{
  "richContent": [
    [
      {
        "type": "type-id",
        ...
      },
      {
        "type": "type-id",
        ...
      }
    ],
    [
      {
        "type": "type-id",
        ...
      },
      {
        "type": "type-id",
        ...
      }
    ]
  ]
}

Tenha em atenção que o valor richContent permite um conjunto exterior e vários conjuntos interiores. As respostas numa matriz interna estão associadas num único cartão visual. Quando a matriz exterior contém várias matrizes interiores, são apresentados vários cartões, um para cada matriz interior.

As subsecções restantes descrevem os vários tipos de respostas que pode configurar para um payload personalizado.

Tipo de resposta de informações

O tipo de resposta de informações é um cartão de título simples no qual os utilizadores podem clicar ou tocar.

Captura de ecrã do Messenger

A tabela seguinte descreve os campos:

Nome Tipo Descrição
type de string Tipo de resposta: "info"
title de string Título do cartão
subtitle de string Subtítulo do cartão
image objeto Imagem
image.src objeto Origem da imagem
image.src.rawUrl de string URL público da imagem
actionLink de string URL a seguir quando o cartão recebe cliques

Por exemplo:

{
  "richContent": [
    [
      {
        "type": "info",
        "title": "Info item title",
        "subtitle": "Info item subtitle",
        "image": {
          "src": {
            "rawUrl": "https://example.com/images/logo.png"
          }
        },
        "actionLink": "https://example.com"
      }
    ]
  ]
}

Tipo de resposta de descrição

O tipo de resposta de descrição é um cartão informativo que pode ter várias linhas de texto.

Captura de ecrã do Messenger

A tabela seguinte descreve os campos:

Nome Tipo Descrição
type de string Tipo de resposta: "description"
title de string Título do cartão
text matriz<string> Matriz de strings, em que cada string é renderizada numa nova linha

Por exemplo:

{
  "richContent": [
    [
      {
        "type": "description",
        "title": "Description title",
        "text": [
          "This is text line 1.",
          "This is text line 2."
        ]
      }
    ]
  ]
}

Tipo de resposta de imagem

O tipo de resposta de imagem é um cartão de imagem no qual os utilizadores podem clicar ou tocar.

Captura de ecrã do Messenger

A tabela seguinte descreve os campos:

Nome Tipo Descrição
type de string Tipo de resposta: "image"
rawUrl de string URL público da imagem
accessibilityText de string Texto alternativo da imagem

Por exemplo:

{
  "richContent": [
    [
      {
        "type": "image",
        "rawUrl": "https://example.com/images/logo.png",
        "accessibilityText": "Example logo"
      }
    ]
  ]
}

Tipo de resposta do botão

O tipo de resposta de botão é um pequeno botão com um ícone que os utilizadores podem clicar ou tocar.

Captura de ecrã do Messenger

A tabela seguinte descreve os campos:

Nome Tipo Descrição
type de string Tipo de resposta: "button"
icon objeto Ícone do botão
icon.type de string Ícone da biblioteca de ícones Material. O ícone predefinido é uma seta
icon.color de string Código hexadecimal da cor
text de string Texto do botão
link de string URL a seguir quando o botão é clicado
event objeto Evento de agentes conversacionais (Dialogflow CX) que é acionado quando se clica no botão.

Por exemplo:

{
  "richContent": [
    [
      {
        "type": "button",
        "icon": {
          "type": "chevron_right",
          "color": "#FF9800"
        },
        "text": "Button text",
        "link": "https://example.com",
        "event": {
          "name": ""
        }
      }
    ]
  ]
}

Tipo de resposta da lista

O tipo de resposta de lista é um cartão com várias opções que os utilizadores podem selecionar.

Captura de ecrã do Messenger

A resposta contém uma matriz de tipos de respostas list e divider. A tabela seguinte descreve o tipo list:

Nome Tipo Descrição
type de string Tipo de resposta: "list"
title de string Título da opção
subtitle de string Subtítulo da opção
event objeto Evento de agentes conversacionais (Dialogflow CX) que é acionado quando a opção é clicada.

A tabela seguinte descreve o tipo divider:

Nome Tipo Descrição
type de string Tipo de resposta: "divider"

Por exemplo:

{
  "richContent": [
    [
      {
        "type": "list",
        "title": "List item 1 title",
        "subtitle": "List item 1 subtitle",
        "event": {
          "name": ""
        }
      },
      {
        "type": "divider"
      },
      {
        "type": "list",
        "title": "List item 2 title",
        "subtitle": "List item 2 subtitle",
        "event": {
          "name": ""
        }
      }
    ]
  ]
}

Tipo de resposta de acordeão

O tipo de resposta de acordeão é um pequeno cartão que um utilizador pode clicar ou tocar para expandir e revelar mais texto.

Captura de ecrã do Messenger

A tabela seguinte descreve os campos:

Nome Tipo Descrição
type de string Tipo de resposta: "acordeão"
title de string Título do acordeão
subtitle de string Subtítulo do acordeão
image objeto Imagem
image.src objeto Origem da imagem
image.src.rawUrl de string URL público da imagem
text de string Texto do acordeão

Por exemplo:

{
  "richContent": [
    [
      {
        "type": "accordion",
        "title": "Accordion title",
        "subtitle": "Accordion subtitle",
        "image": {
          "src": {
            "rawUrl": "https://example.com/images/logo.png"
          }
        },
        "text": "Accordion text"
      }
    ]
  ]
}

Tipo de resposta do chip de sugestão

O tipo de resposta do chip de sugestão fornece ao utilizador final uma lista de chips de sugestão clicáveis.

Captura de ecrã do Messenger

A tabela seguinte descreve os campos:

Nome Tipo Descrição
type de string Tipo de resposta: "chips"
options array<object> Matriz de objetos Option
options[].text de string Texto da opção
options[].image objeto Imagem da opção
options[].image.src objeto Origem da imagem da opção
options[].image.src.rawUrl de string URL público opcional para a imagem
options[].link de string Link da opção

Por exemplo:

{
  "richContent": [
    [
      {
        "type": "chips",
        "options": [
          {
            "text": "Chip 1",
            "image": {
              "src": {
                "rawUrl": "https://example.com/images/logo.png"
              }
            },
            "link": "https://example.com"
          },
          {
            "text": "Chip 2",
            "image": {
              "src": {
                "rawUrl": "https://example.com/images/logo.png"
              }
            },
            "link": "https://example.com"
          }
        ]
      }
    ]
  ]
}

Combinar tipos de respostas

Os elementos de mensagens multimédia individuais do Dialogflow CX Messenger podem ser usados para criar um cartão personalizado de acordo com as suas necessidades. Segue-se um exemplo que usa alguns dos elementos indicados acima:

Captura de ecrã do Messenger

{
  "richContent": [
    [
      {
        "type": "image",
        "rawUrl": "https://example.com/images/logo.png",
        "accessibilityText": "Conversational Agents (Dialogflow CX) across platforms"
      },
      {
        "type": "info",
        "title": "Conversational Agents (Dialogflow CX)",
        "subtitle": "Build natural and rich conversational experiences",
        "actionLink": "https://cloud.google.com/dialogflow/docs"
      },
      {
        "type": "chips",
        "options": [
          {
            "text": "Case Studies",
            "link": "https://cloud.google.com/dialogflow/case-studies"
          },
          {
            "text": "Docs",
            "link": "https://cloud.google.com/dialogflow/docs"
          }
        ]
      }
    ]
  ]
}

Depuração

Para testar o seu agente localmente com o Dialogflow CX Messenger:

  • Incorporar o elemento Dialogflow CX Messenger numa página, conforme descrito na secção Personalizações de HTML.
  • Inicie um servidor HTTP local para essa página com uma porta específica.
  • Aceda a essa página em http://localhost:port_number.