Crie um complemento do Google Chat com o Dialogflow ES

Prévia para desenvolvedores:disponível no Programa de prévia para desenvolvedores do Google Workspace, que concede acesso antecipado a determinados recursos.

Nesta página, explicamos como criar um app do Google Chat como um complemento do Google Workspace que usa o Dialogflow ES para entender e responder em linguagem natural. Você também pode usar o Dialogflow CX, que tem uma integração direta com o Google Chat, para criar um app do Google Chat com o Dialogflow CX seguindo o guia Google Chat do Dialogflow CX.

Objetivos

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

Pré-requisitos

• Uma conta do Google Workspace Business ou Enterprise com acesso ao Google Chat.
• Ter um projeto do Google Cloud com o faturamento ativado. Para verificar se um projeto já tem o faturamento ativado, 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 interagindo com um app de 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 reside em , recebe e processa a mensagem para produzir uma resposta.
3. Como opção, 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 tíquetes.
4. O agente do Dialogflow envia uma resposta de volta para o serviço do app Chat no Chat.
5. A resposta é enviada para o espaço do Chat.

Configure o ambiente

Antes de usar as APIs do Google, é necessário 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 de APIs do Google, ative as APIs Google Chat e Dialogflow.

   Ativar as APIs

2. Confirme se você está ativando as APIs no projeto do Cloud correto e clique em Próxima.

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

Criar um agente do Dialogflow ES

Se você não tiver um agente do Dialogflow ES:

1. Acesse o Console do Dialogflow ES.
2. Clique em Create Agent.
3. Dê um nome a ele e selecione um idioma padrão e um fuso horário.
4. Associe-o ao seu projeto do Cloud.
5. Clique em Criar.
6. Crie intents e entidades conforme necessário para o fluxo de conversa do seu app de chat. Você pode começar com uma intent de saudação.
7. Anote o ID do projeto.

Para um guia detalhado, consulte Criar um agente.

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

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

1. No console de APIs do Google, 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. Em 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 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 ES.
   7. Disponibilize o app de chat para pessoas e grupos específicos no seu domínio e digite seu endereço de e-mail.
   8. 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 ES enviando uma mensagem para ele no Google Chat.

1. Abra o Google Chat usando a conta do Google Workspace que você informou ao se tornar um testador de confiança.

   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 seu app de 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 de APIs do Google.

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

   O app Dialogflow Chat responde com uma mensagem de saudação.

Respostas de texto

As respostas de texto são enviadas ao Google Chat como mensagens de texto. Com essa formatação, você pode deixar o texto em negrito ou em itálico ao encapsular o texto em determinados símbolos (Markdown leve).

A resposta da mensagem de texto parece visualmente igual à resposta de texto padrão no console do Dialogflow. No entanto, a resposta bruta da API será um pouco diferente. Ele também define a configuração da plataforma como GOOGLE_HANGOUTS, o que pode ser interessante ao criar agentes para várias integrações.

"fulfillmentMessages": [
{
   "text": {
   "text": [
        "This is a test."
   ]
},
  "platform": "GOOGLE_HANGOUTS"
},

Cartões

As respostas de cards são enviadas ao Google Chat como mensagens de card.

Imagens

As respostas de imagem são enviadas ao Google Chat como widgets de imagem do Google Chat.

Payload personalizado

Para enviar outros tipos de mensagens do Google Chat, use um payload personalizado.

Com o payload personalizado do Google Chat, você pode criar cards mais avançados. Um card pode ter uma ou várias seções. Cada seção pode ter um cabeçalho. Confira o guia de referência de cards de complementos do Google Workspace para ampliar o Chat e ver algumas das combinações que você pode criar com isso. No entanto, se você usa payloads personalizados, será necessário fornecer o formato JSON.

Observação: ao copiar e colar os exemplos do guia de referência na caixa de payload personalizado no Dialogflow, verifique se o editor não contém erros de inspeção. Não é possível testar os resultados no simulador do Dialogflow, mas é possível testá-los diretamente no Google Chat.

Este é um exemplo de payload personalizado para criar uma mensagem com um card:

{ "hangouts": { "hostAppDataAction": { "chatDataAction": {
  "createMessageAction": { "message": { "cardsV2": [{
    "cardId": "pizza",
    "card": {
      "header": {
        "title": "Pizza Delivery Customer Support",
        "subtitle": "[e-mail]",
        "imageUrl": "https://goo.gl/aeDtrS"
      },
      "sections": [{ "widgets": [{ "textParagraph": {
        "text": " Your pizza is here!"
      }}]}]
    }
  }]}}
}}}}

Limitações e considerações

• Ao usar complementos do Google Workspace com o Dialogflow, os objetos de evento de chat têm as seguintes limitações e considerações:
  • Eventos da página inicial do app:ainda não há suporte para eventos APP_HOME.
  • Entrada de consulta do Dialogflow:o texto enviado como entrada de consulta ao agente do Dialogflow depende do tipo de evento:
    • MESSAGE:o valor do campo argumentText da mensagem de chat.
    • APP_COMMAND:a string "APP_COMMAND_PAYLOAD".
    • ADDED_TO_SPACE:um evento de boas-vindas padrão é enviado.
    • REMOVED_FROM_SPACE:a string "REMOVED_FROM_SPACE_PAYLOAD".
    • CARD_CLICKED:a string "BUTTON_CLICKED_PAYLOAD".
    • WIDGET_UPDATED:a string "WIDGET_UPDATED_PAYLOAD" (usada para preenchimento automático).
  • Payload completo do evento:o payload JSON completo do evento de interação do chat é enviado ao Dialogflow no campo WebhookRequest.payload. Você pode acessar isso no seu webhook do Dialogflow. Para mais informações, consulte a documentação de solicitação de webhook do Dialogflow ES.
• Considerações para responder a comandos e receber dados de cards ou caixas de diálogo:
  • Se o agente do Dialogflow precisar processar o payload JSON do evento de interação de chat, ele poderá fazer isso usando um webhook do Dialogflow para inspecionar o payload personalizado no parâmetro de consulta.
  • Para mostrar uma caixa de diálogo do agente do Dialogflow, responda com um único payload JSON personalizado que contenha um objeto RenderActions com a navegação pushCard.
  • Para processar dados inseridos em cards, use um webhook do Dialogflow e responda com um único payload JSON personalizado que contenha a ação apropriada.
• As visualizações de links não são compatíveis.
• 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 ao Chat de forma assíncrona chamando o método create no recurso spaces.messages da API do Chat uma vez para cada mensagem.
• Ao usar a integração do Dialogflow ES com o Chat, o agente do Dialogflow e o app Chat precisam ser configurados no mesmo projeto do Google Cloud.

Resolver problemas

Para depurar seu app do Chat, comece revisando os registros de erros. Como esse app usa o Dialogflow, você tem vários recursos de geração de registros e solução de problemas disponíveis:

• Registros de complementos do Google Workspace:consulte os registros para informações detalhadas sobre o comportamento do complemento, incluindo as interações dele com o Chat. Consulte Consultar registros de complementos do Google Workspace.

• Erros do app Google Chat:para mensagens de erro e correções gerais do app Chat, consulte Resolver problemas e corrigir erros do app Chat.

• Histórico de conversas do Dialogflow ES:Histórico | Dialogflow ES

• Solução de problemas gerais do Dialogflow:Solução de problemas | Dialogflow

Limpar

Para evitar cobranças na sua conta do 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 todo o projeto.

Se você planeja explorar 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 de APIs do Google, 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 excluí-lo.

Temas relacionados

• O Dialogflow CX é outra maneira de usar o Dialogflow com um app de chat.