Criar um app do Google Chat para Dialogflow CX que entende e responde com linguagem natural

Esta página explica como criar um app do Google Chat que entenda e responda com linguagem natural usando o Dialogflow. Este guia usa o Dialogflow CX, que tem uma integração direta com o Google Chat. Também é possível usar o Dialogflow ES para criar um app do Google Chat seguindo o guia Dialogflow ES Google Chat.

Por exemplo, pense em um app de chat que ajuda pessoas que querem alugar carros. Um usuário escreve "Quero alugar um carro". O app do Chat pode responder com uma pergunta como "Onde você quer retirar o veículo?", o que dá início a uma conversa semelhante à de pessoas. Nesse caso, o app do Chat entende e responde em linguagem natural enquanto agenda o aluguel do carro.

Esse é apenas um exemplo. Os apps do Chat do Dialogflow são úteis para todos os tipos de interação. Se ela exigir linguagem natural, será necessário um app do Dialogflow Chat. Os agentes predefinidos ajudam você a começar rapidamente e mostram o que o Dialogflow pode fazer, como:

• Reservar voos
• Agendar consultas médicas
• Pedir comida para entrega
• Responder a perguntas sobre um catálogo de produtos de varejo, como se os itens estão disponíveis em outras cores

• 

  Figura 1. Como selecionar um agente pré-criado para um app do Chat do Dialogflow.

• 
  Figura 2. Testar o agente no Dialogflow CX para garantir que a lógica e a configuração dele funcionem conforme o esperado. O diagrama mostra um conjunto sequencial de páginas temáticas que se referem a etapas específicas da conversa, como definir um local de retirada e devolução de um carro alugado, e configura a lógica que as conecta. A conversa é testada em um simulador.
• 
  Figura 3. Configurar um app do Chat para processar respostas usando o agente do Dialogflow CX na página de configuração da API Chat no console do Google Cloud.
• 
  Figura 4. Uma conversa sobre a reserva de um carro alugado com o app Chat do Dialogflow no Google Chat.

Objetivos

• Prepare o ambiente.
• Crie e implante um agente do Dialogflow CX.
• Crie e implante um app de chat com o agente do Dialogflow CX.
• Teste o app Chat.

Pré-requisitos

• Uma conta do Google Workspace para empresas ou empresas com acesso ao Google Chat.
• Ter um projeto do Google Cloud com o faturamento ativado. Para verificar se o faturamento está ativado em um projeto, consulte Verificar o status de faturamento dos seus projetos. Para criar um projeto e configurar o faturamento, consulte Criar um projeto do Google Cloud.

Arquitetura

O diagrama a seguir mostra a arquitetura de um app de chat criado com o Dialogflow:

No diagrama anterior, um usuário que interage com um app do Chat do Dialogflow tem o seguinte fluxo de informações:

1. Um usuário envia uma mensagem no Chat para um app do Chat, em uma mensagem direta ou em um espaço do Chat.
2. Um agente virtual do Dialogflow, que fica no Google Cloud, recebe e processa a mensagem para produzir uma resposta.
3. Opcionalmente, usando um webhook do Dialogflow, o agente do Dialogflow pode interagir com serviços externos de terceiros, como um sistema de gerenciamento de projetos ou uma ferramenta de emissão de passagens.
4. O agente do Dialogflow envia uma resposta de volta para o serviço do app Chat.
5. A resposta é enviada para o espaço do Chat.

Configure o ambiente

Antes de usar as APIs do Google, você precisa ativá-las em um projeto do Google Cloud. É possível ativar uma ou mais APIs em um único projeto do Google Cloud.

1. No console do Google Cloud, ative a API Google Chat e a API Dialogflow.

   Ativar as APIs

2. Confirme que você está ativando as APIs no projeto correto do Cloud e clique em Next.

3. Confirme se você está ativando as APIs corretas e clique em Ativar.

Criar um agente do Dialogflow CX

Um agente do Dialogflow CX é um agente virtual que processa conversas simultâneas com seus usuários finais. Ele é um módulo de compreensão de linguagem natural que entende as nuances da fala humana. O Dialogflow converte textos do usuário final durante uma conversa em dados estruturados que seus apps e serviços podem entender. Você projeta e cria um agente do Dialogflow para atender aos tipos de conversas necessárias para seu sistema.

Um agente do Dialogflow é como um agente humano de call center. Você o treina para que lide com os cenários esperados em conversas, e o treinamento não precisa ser muito detalhado.

Veja como criar o agente do Dialogflow CX:

1. No console do Dialogflow CX, abra o console do Dialogflow CX. Clique em Menu > Dialogflow CX.

   Acessar o console do Dialogflow CX

2. Escolha um projeto do Google Cloud. Para encontrar seu projeto, talvez seja necessário clicar em Todos e pesquisar.

3. Agora você tem a opção de escolher um agente pré-criado ou criar o seu. Se você preferir explorar a personalização de agentes em detalhes mais tarde, escolha um dos agentes predefinidos, que também são úteis para saber o que os agentes podem fazer.

   Para escolher um agente predefinido, siga estas etapas:

   1. Clique em Usar agentes predefinidos.

   2. Selecione um agente pré-criado. Para este guia, selecione Viagens: aluguel de carros.

      Os agentes são classificados como iniciantes, intermediários ou avançados com base na quantidade de recursos que usam e na sofisticação da lógica de conversa. A escolha de um agente intermediário ou avançado pode exigir personalizações e configurações específicas do agente, incluindo a ativação de recursos e APIs no console do Google Cloud.

   3. Clique em Importar como agente.

   Para criar seu próprio agente, siga estas etapas:

   1. Clique em Criar agente.
   2. Selecione Gerar automaticamente para criar um agente de repositório de dados ou Criar seu próprio para criar outros tipos de agentes.

   Para um tutorial detalhado do processo de criação de agentes, consulte Criar um agente do Dialogflow CX.

4. Defina as configurações básicas do agente:

   1. Em Nome de exibição, insira um nome de exibição.
   2. Selecione um local. Se você quiser mudar as configurações avançadas de local, clique em Editar.
   3. Selecione o fuso horário.
   4. Selecione o idioma padrão do agente. Não é possível mudar o idioma padrão de um agente após a criação.

5. Clique em Criar. O Dialogflow CX começa a criar o agente e, em seguida, mostra o fluxo de início padrão dele.

6. Opcionalmente, personalize o agente. Para uma explicação detalhada do processo de personalização do agente, consulte Criar um agente do Dialogflow CX.

7. Como prática recomendada, teste o agente:

   1. Clique em Testar agente.
   2. Selecione Testar agente no ambiente.
   3. Em "Ambiente", selecione Rascunho.
   4. Em "Fluxo", selecione Fluxo inicial padrão.
   5. Em "Página", selecione Página inicial.
   6. Na barra de composição Falar com o agente, digite Hello e pressione Enter. O agente responde se apresentando.
   7. Conclua o teste fazendo a conversa de teste de exemplo.

8. O agente do Dialogflow CX é criado. Volte ao console do Dialogflow CX. Clique em Menu > Dialogflow CX.

   Acessar o console do Dialogflow CX

9. Em Agentes, clique em > Copiar nome. Salve esse nome, porque ele será usado ao configurar o app Chat.

Criar um app de chat e conectá-lo ao agente do Dialogflow

Depois de criar um agente do Dialogflow CX, siga estas etapas para transformá-lo em um app de chat:

1. No console do Google Cloud, acesse a API Google Chat. Pesquise "API Google Chat" e clique em API Google Chat e em Gerenciar.

   Acessar a API Chat

2. Clique em Configuração e configure o app Chat:

   1. Em Nome do app, insira Dialogflow App.
   2. No URL do avatar, digite https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png.
   3. Em Descrição, insira Responds to real human conversation.
   4. Em Funcionalidade, selecione Receber mensagens individuais e Participar de espaços e conversas em grupo.
   5. Em Configurações de conexão, selecione Dialogflow.
   6. Em Configurações do Dialogflow, selecione Dialogflow CX.
   7. Em Nome do recurso do agente ou do ambiente, cole o nome do agente do Dialogflow CX que você copiou no final de Criar um agente do Dialogflow CX.
   8. Disponibilidade do app de chat para pessoas e grupos específicos no seu domínio e insira seu endereço de e-mail.
   9. Em Registros, selecione Registrar erros no Logging.

3. Clique em Salvar.

O app Chat está pronto para receber e responder a mensagens.

Teste o app do Chat

Teste o app de chat do Dialogflow CX enviando mensagens para ele no Google Chat.

1. Abra o Google Chat usando a conta do Google Workspace que você informou ao se adicionar como um testador confiável.

   Acessar o Google Chat

2. Clique em Novo chat.
3. No campo Adicionar uma ou mais pessoas, digite o nome do seu app Chat.

4. Selecione o app Chat nos resultados. Uma mensagem direta é aberta.

   Observação:se o app de chat não aparecer na lista de resultados, verifique se você incluiu sua conta do Google Workspace nas configurações de Visibilidade da página Configuração da API Chat no console do Google Cloud.

5. Na nova mensagem direta com o app, digite Hello e pressione enter.

   O app Dialogflow Chat responde se apresentando.

6. Conclua o teste fazendo a conversa de teste de exemplo.

Exemplo de conversa de teste

Para testar o app de chat do Dialogflow CX no console do Dialogflow CX ou no Google Chat, faça a seguinte conversa. A explicação ajuda você a entender como o agente do Dialogflow CX interpreta a linguagem natural do usuário e produz a própria resposta de linguagem natural em cada etapa da conversa. Esta conversa de exemplo é baseada no agente predefinido chamado Viagens: aluguel de carros.

Dialog	Explicação
Usuário final:Olá Agente:Olá! Sou o agente virtual de aluguel de carros. Posso ajudar você a iniciar uma nova reserva de aluguel de carro. Como posso ajudar?	A rota de intent de boas-vindas padrão no Fluxo inicial padrão é chamada. O fulfillment desse manipulador de estado ("Olá, Estou…") foi adicionado à fila de respostas. O agente envia a fila de resposta para o usuário final.
Usuário final:Quero alugar um carro. Agente:Onde você quer retirar o veículo?	A rota de intent car_rental.reservation_create na página inicial é correspondida. A sessão é transferida para a página Local de retirada. O formulário da página Local de retirada não está completo. Portanto, o agente usa o parâmetro pickup_location para solicitar ao usuário ("Onde você gostaria de retirar..."), que é adicionado à fila de respostas. O agente envia a fila de resposta para o usuário final.
Usuário final:Las Vegas Agente:Ok, a retirada será em Las Vegas. Agente:o local de entrega é diferente do local de retirada?	A entrada do usuário final preenche o parâmetro pickup_location solicitado pelo agente na fala anterior. A rota de intent car_rental.return_different_location no Fluxo inicial padrão é correspondida. A rota de preenchimento do formulário na página Local de retirada é avaliada e chamada. Ela tem um fulfillment ("Ok, sua retirada..."), que é adicionado à fila de respostas e com as referências de parâmetros resolvidas para valores reais fornecidos pelo usuário final. A sessão é transferida para a página Confirmar local. A página Confirmar local tem um fulfillment de entrada ("O local de entrega é diferente..."), que é adicionado à fila de respostas. O agente envia a fila de resposta para o usuário final.
Usuário final:sim. Vou deixar o carro em Los Angeles. Agente:Ok, seu destino é Los Angeles. Agente:em que data e horário você quer retirar o veículo?	A rota de intent car_rental.return_different_location no Fluxo inicial padrão é correspondida. A sessão é transferida para a página Local de entrega. A entrada do usuário final preenche o parâmetro drop_off_location solicitado pelo agente na fala anterior. A rota de preenchimento do formulário na página Local de entrega é avaliada e chamada. Ela tem um fulfillment ("Ok, seu envio..."), que é adicionado à fila de respostas. A sessão é transferida para a página Duração do aluguel. A página Duração do aluguel tem valores de formulário incompletos. Por isso, ela solicita ao usuário o parâmetro pickup_date_time ("Em que data e hora você quer retirar o carro?"). que é adicionado à fila de respostas. O agente envia a fila de resposta para o usuário final.
Usuário final:Gostaria de retirar o carro no dia 5 de março, ao meio-dia. Agente:Em que data e horário você quer devolver o veículo?	A entrada do usuário final preenche o parâmetro pickup_date_time solicitado pelo agente na fala anterior. A página Rental Duration tem outro valor de formulário ausente, então ela solicita ao usuário o parâmetro drop_off_date_time ("What date and time would you like to drop off…"), que é adicionado à fila de respostas. O agente envia a fila de resposta para o usuário final.
Usuário final:15 de março, meio-dia. Agente:Para confirmar: O veículo será retirado em Las Vegas 2024-03-05 12:00:00 e deixado em Los Angeles 2024-03-15 12:00:00 Isso está correto?	A entrada do usuário final preenche o parâmetro drop_off_date_time solicitado pelo agente na fala anterior. A sessão é transferida para a página Confirmar duração do aluguel. A página Confirmar duração do aluguel tem um fulfillment de entrada ("Para confirmar..."), que é adicionado à fila de respostas. O agente envia a fila de resposta para o usuário final.
Usuário final:sim, obrigado. Agente:ótimo. Agora vamos escolher um veículo. Agente:Você quer um veículo econômico ou de luxo?	A rota da intent small_talk.confirmation.yes na página Confirm Rental Duration é correspondida. O agente confirma a escolha do usuário com uma mensagem ("Ótimo! Agora vamos escolher..."), que é adicionado à fila de respostas. A sessão é transferida para a página Desambiguação do veículo. O formulário da página Vehicle Disambiguation não está completo. Portanto, o agente usa o parâmetro vehicle_type para solicitar que o usuário ("Você quer um carro econômico ou de luxo?"), que é adicionado à fila de respostas. O agente envia a fila de resposta para o usuário final.
Usuário final:Economy, por favor. Agente:Você quer o carro ou o caminhão da Cymbal?	A rota de intent $session.params.vehicle_type="economy_vehicle" é correspondida. A sessão é transferida para a página Opções de classe econômica. A página Opções econômicas tem um fulfillment de entrada ("Você gostaria de..."), que é adicionado à fila de respostas. O agente envia a fila de resposta para o usuário final.
Usuário final:Cymbal Truck. Agente:O Cymbal Truck custa US $50,33 por dia. Ele acomoda 4 pessoas e vem com um rádio AM/FM. Quer continuar para o pagamento? Usuário final:sim.	A rota de intent $session.params.vehicle_type="Cymbal Truck" é correspondente, e o parâmetro vehicle_model é preenchido. A sessão é transferida para a página Confirm Cymbal Truck. A página Confirm Cymbal Truck tem um fulfillment de entrada ("O Cymbal Truck custa US $50,33 por dia..."), que é adicionado à fila de respostas. O agente envia a fila de resposta para o usuário final. A resposta do usuário corresponde à rota small_talk.confirmation.yes.
Agente:que tipo de cartão você vai usar? Usuário final:Altostrat Agente:insira o número do cartão. Usuário final:1234 1234 1234 1234 Agente:Qual é o nome no cartão? Usuário final:Charlie Agente:Qual é o endereço de faturamento? Usuário final:1800 Amphibious Blvd., Mountain View, CA Agente:qual é o CEP de faturamento? Usuário final:94045 Agente:você vai buscar o Cymbal Car em Las Vegas, em 2024-03-05 12:00:00, e deixá-lo em 2024-03-15 12:00:00. O total desta viagem será de US$ 175,38. Agente:Agradecemos por alugar conosco. Tenha um ótimo dia.	A sessão é transferida para a página Pagamento. O formulário de pagamento não está completo, então o agente solicita ao usuário os parâmetros card_type, card_number, billing_name, billing_street_address e billing_zip_code ("Qual tipo de cartão vai..."), que são adicionados sequencialmente à fila de respostas e enviados conforme o usuário responde. As respostas do usuário definem cada valor de parâmetro. A sessão é transferida para a página de Confirmação da locação. A página Confirmação de aluguel tem um fulfillment de entrada ("Ok, sua retirada será..."), que é adicionado à fila de respostas. O agente envia a fila de resposta para o usuário final. A sessão é transferida para a página Encerrar sessão.

Enviar mensagens de cards do Dialogflow

Codelab:para conferir um exemplo prático de envio de mensagens de card no Dialogflow, consulte Mostrar fontes nas respostas do app de conhecimento do Chat no codelab "Criar apps para o Google Chat com o Gemini".

O Dialogflow pode responder com mensagens de texto ou cartão. Para responder com uma mensagem de cartão, especifique-a como um payload personalizado em fulfillment.

O JSON a seguir mostra como enviar uma mensagem de cartão como um payload personalizado no fulfillment:

json

{
  'cardsV2': [{
    'cardId': 'createCardMessage',
    'card': {
      'header': {
        'title': 'A card message!',
        'subtitle': 'Sent from Dialogflow',
        'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png',
        'imageType': 'CIRCLE'
      },
      'sections': [
        {
          'widgets': [
            {
              'buttonList': {
                'buttons': [
                  {
                    'text': 'Read the docs!',
                    'onClick': {
                      'openLink': {
                        'url': 'https://developers.google.com/workspace/chat'
                      }
                    }
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  }]
}

Limites e considerações

• Os eventos de interação no chat têm suporte limitado e algumas considerações:
  • Os seguintes tipos de eventos de interação são aceitos:
    • MESSAGE
    • ADDED_TO_SPACE
    • CARD_CLICKED
  • Para eventos MESSAGE ou ADDED_TO_SPACE, a entrada de consulta enviada ao agente do Dialogflow corresponde ao valor do campo argumentText na mensagem de chat. Se a mensagem incluir um comando de barra, o valor do campo text será usado.
  • Para eventos CARD_CLICKED, a entrada de consulta enviada ao agente do Dialogflow é formatada como CARD_CLICKED.functionName, em que functionName corresponde ao valor do campo function do objeto Action anexado ao elemento de card interativo (como um botão).
  • O payload JSON completo de cada evento de interação do Chat é enviado ao Dialogflow como um payload personalizado no parâmetro de consulta e pode ser acessado com um webhook do Dialogflow consultando o valor do campo WebhookRequest.payload.
• Considerações para responder a comandos de barra e receber dados de cards ou caixas de diálogo:
  • Quando os apps do Dialogflow Chat recebem uma mensagem com um comando de barra obrigatória, a entrada de consulta contém apenas o valor do campo text. O campo text começa com o nome do comando de barra (por exemplo, /command), que pode ser usado para configurar a intenção de um agente do Dialogflow para detectar um comando de barra.
  • Se o agente do Dialogflow precisar processar o payload JSON do evento de interação por chat, ele poderá fazer isso usando um webhook do Dialogflow para inspecionar o payload personalizado no parâmetro de consulta.
  • Para mostrar uma conversa do agente do Dialogflow, responda com um único payload JSON personalizado que inclua uma mensagem com uma resposta de ação DIALOG.
  • Para processar os dados inseridos em cards, o agente do Dialogflow pode detectar intenções que começam com o texto CARD_CLICKED e responder com um único payload JSON personalizado que contém a ação adequada.
• Não é possível usar visualizações de links.
• Se o agente do Dialogflow responder com apenas uma mensagem, ela será enviada ao Google Chat de forma síncrona. Se o agente do Dialogflow responder com várias mensagens, todas elas serão enviadas para o Chat de forma assíncrona chamando o método create no recurso spaces.messages na API Chat uma vez para cada mensagem.
• Ao usar a integração do Dialogflow CX com o Chat, o agente do Dialogflow e o app Chat precisam ser configurados no mesmo projeto do Google Cloud. Se você precisar configurar o Dialogflow e o Chat em diferentes projetos do Cloud, poderá configurar um servidor intermediário para facilitar a conexão. Para saber como, consulte este exemplo de integração de chat para o Dialogflow CX no GitHub.

Resolver problemas

Quando um app do Google Chat ou um card retorna um erro, a interface do Chat mostra uma mensagem informando que "Ocorreu um erro". ou "Não foi possível processar sua solicitação". Às vezes, a interface do Chat não mostra nenhuma mensagem de erro, mas o app ou o card do Chat produz um resultado inesperado. Por exemplo, uma mensagem de card pode não aparecer.

Embora uma mensagem de erro possa não aparecer na interface do Chat, mensagens de erro descritivas e dados de registro estão disponíveis para ajudar a corrigir erros quando o registro de erros para apps de chat estiver ativado. Para saber como visualizar, depurar e corrigir erros, consulte Resolver e corrigir erros do Google Chat.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste tutorial, recomendamos que você exclua o projeto do Cloud.

Cuidado:excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para seguir este tutorial, a exclusão dele incluirá quaisquer outras ações feitas no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL em appspot.com, exclua os recursos selecionados dentro do projeto em vez de excluir o projeto inteiro.

Se você planeja conferir vários tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

1. No console do Google Cloud, acesse a página Gerenciar recursos. Clique em Menu > IAM e administrador > Gerenciar recursos.

   Acesse o Resource Manager

2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluir o projeto.

Temas relacionados

• O Dialogflow CX usa uma abordagem de máquina de estado para o design de agentes do Dialogflow, que oferece um controle claro e explícito sobre uma conversa, uma melhor experiência do usuário final e um melhor fluxo de trabalho de desenvolvimento. Ao criar um app do Dialogflow Chat, recomendamos usar o Dialogflow CX.
  • Para saber mais sobre a criação e configuração de agentes, consulte Agentes do Dialogflow CX.
  • Para um tutorial detalhado sobre como criar e configurar agentes, consulte Criar um agente do Dialogflow CX.
  • Codelab:para conferir um exemplo de como criar um agente de repositório de dados do Dialogflow CX, consulte o app de chat de conhecimento do codelab Criar apps para o Google Chat com o Gemini.
  • Codelab:para conferir um exemplo de como criar um agente de conversação do Dialogflow CX, consulte o app de chat de feedback do codelab Criar apps para o Google Chat com o Gemini.
• O Dialogflow ES é outra maneira de usar o Dialogflow com um app de chat.