A integração do Dialogflow Messenger 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ã.
Limitações
- Apenas o idioma do agente predefinido é suportado por esta integração.
Configure e teste
Para configurar e ativar o Dialogflow Messenger:
- Aceda à consola do Dialogflow ES.
- Clique em Integrações no menu da barra lateral esquerda.
- Clique em Dialogflow Messenger.
- É aberta uma caixa de diálogo de configuração.
- Escolha um ambiente.
- Clique em Ativar.
- Copie o código de incorporação para colar no seu Website.
- Clique em Experimentar agora para testar o seu agente.
- No canto inferior direito da janela, é apresentado um botão com o logótipo do Dialogflow. Clique neste botão.
- É aberta uma caixa de diálogo do chat com a qual pode interagir.
- Feche a caixa de diálogo do chat quando terminar os testes.
- Clique em Fechar na caixa de diálogo de configuração.
Incorporar
Cole o código de incorporação que copiou acima numa página Web do seu Website.
Os elementos HTML <script> e <df-messenger> devem estar no elemento <body> da sua página.
Para permitir esquemas adaptáveis,
adicione também o seguinte à sua página:
<meta name="viewport" content="width=device-width, initial-scale=1">
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 do Dialogflow. 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 do Dialogflow é 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. |
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 | O evento usado para acionar a primeira intenção quando a caixa de diálogo de chat é aberta. Este campo é pré-preenchido com o evento WELCOME. |
language-code |
Obrigatória | Código do idioma predefinido para a primeira intenção. Este campo é pré-preenchido com o idioma predefinido 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 para o Dialogflow através do campo queryParams.payload.userId num pedido de deteção de intenção. |
wait-open |
Opcional | Atributo booleano que atrasa o evento de boas-vindas 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:
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,
parameters: {},
languageCode: 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 tivesse sido enviada pelo Dialogflow como uma 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 tivesse sido enviado pelo Dialogflow como uma mensagem de resposta avançada. O formato da resposta de payload personalizado é definido na secção Mensagens de resposta avançadas.
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();
Mensagens de resposta avançadas
Quando cria mensagens de resposta avançadas, pode criar respostas de texto e payloads personalizados no separador de respostas Predefinição para a intenção. 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.
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.
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.
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.
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 do Dialogflow que é acionado quando se clica no botão. Consulte a referência REST EventInput |
Por exemplo:
{
"richContent": [
[
{
"type": "button",
"icon": {
"type": "chevron_right",
"color": "#FF9800"
},
"text": "Button text",
"link": "https://example.com",
"event": {
"name": "",
"languageCode": "",
"parameters": {}
}
}
]
]
}
Tipo de resposta da lista
O tipo de resposta de lista é um cartão com várias opções que os utilizadores podem selecionar.
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 do Dialogflow acionado quando a opção é clicada. Consulte a referência REST EventInput |
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": "",
"languageCode": "",
"parameters": {}
}
},
{
"type": "divider"
},
{
"type": "list",
"title": "List item 2 title",
"subtitle": "List item 2 subtitle",
"event": {
"name": "",
"languageCode": "",
"parameters": {}
}
}
]
]
}
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.
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.
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 enriquecidas individuais para o Dialogflow 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:
{
"richContent": [
[
{
"type": "image",
"rawUrl": "https://example.com/images/logo.png",
"accessibilityText": "Dialogflow across platforms"
},
{
"type": "info",
"title": "Dialogflow",
"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 com o Dialogflow Messenger localmente:
- Incorpore o elemento do Dialogflow Messenger numa página conforme descrito acima.
- Inicie um servidor HTTP local para essa página com uma porta específica.
- Aceda a essa página em
http://localhost:port_number.