Fique doente com um bot personalizado para Hangouts Chat

Os bots do Hangouts Chat fornecem pontos de acesso fáceis de usar para os dados e serviços da sua organização. Os usuários podem interagir com bots em uma experiência de bate-papo.

Entre outras opções de implementação, você pode criar um bot do Hangouts Chat usando o Google Apps Script . Ao criar seu bot no Apps Script, você pode acessar facilmente outros serviços do Google, como Drive, Gmail, Agenda, Documentos, Planilhas e muito mais.

Neste laboratório de código, você aprenderá a criar um bot simples do Hangouts Chat - "Attendance Bot" - usando o Google Apps Script. O bot se integra ao Gmail para definir a resposta automática de férias do usuário e ao Agenda para incluir uma reunião na agenda do usuário.

c0e8d9d0b5d0cf8b.png

O que você aprenderá

  • Como adicionar manipuladores em eventos gerados no Hangouts Chat
  • Como analisar objetos de evento enviados do Hangouts Chat
  • Como responder ao Hangouts Chat com respostas formatadas em cartão
  • Como definir e reagir a ações personalizadas para cliques de botão em cartões

O que você precisará

  • Acesso à Internet e um navegador da web.
  • Conta AG Suite.
  • Habilidades básicas de JavaScript - o Google Apps Script só oferece suporte a JavaScript.

Você pode baixar um arquivo ZIP ou clonar o repositório GitHub para ver o código de cada etapa neste exemplo.

As pastas step-NN contêm o estado final desejado de cada etapa deste codelab. Eles estão lá para referência.

Baixe o código

Clique no link a seguir para baixar todo o código deste codelab:

Baixe o código fonte

Descompacte o arquivo zip baixado. Isso descompactará uma pasta raiz ( hangouts-chat-apps-script ), que contém uma pasta para cada etapa deste codelab.

Clonando o repositório GitHub

Para clonar o repositório GitHub para este codelab, execute o seguinte comando:

git clone https://github.com/googlecodelabs/hangouts-chat-apps-script

Para começar a implementar seu bot, crie um novo script do Google Apps Script fazendo o seguinte:

  1. Em seu navegador, abra o editor do Google Apps Script .
  2. Clique em Arquivo> Renomear ... e renomeie o novo script como 'Attendance Bot'.

Eventos no Hangouts Chat

A maioria das interações do bot do Apps Script com o Hangouts Chat são baseadas em eventos. A interação entre o usuário, o bot e o bate-papo do Hangouts normalmente segue esta sequência:

  1. Um usuário inicia uma ação, como adicionar um bot a uma sala, iniciar uma mensagem direta (DM) com um bot ou remover o bot de uma sala.
  2. A ação gera um evento direcionado ao bot no Hangouts Chat.
  3. O Hangouts Chat chama o manipulador de eventos correspondente definido no script do bot.

O Hangouts Chat gera quatro eventos que seu bot do Apps Script pode escutar:

  • ADDED_TO_SPACE : Este evento ocorre quando um usuário humano adiciona um bot a uma sala ou uma mensagem direta (DM). No Apps Script, você define uma função onAddToSpace() para lidar com esse evento.
  • REMOVED_FROM_SPACE : Este evento ocorre quando um usuário remove o bot de uma sala ou DM. Este evento não posta uma resposta no Hangouts Chat. No Apps Script, você define uma função onRemoveFromSpace() para lidar com esse evento.
  • MESSAGE : Este evento ocorre quando um usuário envia uma mensagem ao bot, seja diretamente em um DM ou como uma @ menção em uma sala. No Apps Script, você define uma função onMessage() para responder a esse evento.
  • CARD_CLICKED : Este evento ocorre quando o usuário clica em um botão com uma ação personalizada atribuída a ele. No Apps Script, você define uma função onCardClick() para responder a esse evento.

Substitua o conteúdo do Code.gs arquivo com o seguinte código que define manipuladores para os ADDED_TO_SPACE e REMOVE_FROM_SPACE eventos. (Você adicionará manipuladores para os eventos MESSAGE e CARD_CLICKED posteriormente neste codelab.)

Code.gs

/**
 * Responds to an ADDED_TO_SPACE event in Hangouts Chat.
 * @param {object} event the event object from Hangouts Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/hangouts/chat/reference/message-formats/events
 */
function onAddToSpace(event) {
  console.info(event);
  var message = 'Thank you for adding me to ';
  if (event.space.type === 'DM') {
    message += 'a DM, ' + event.user.displayName + '!';
  } else {
    message += event.space.displayName;
  }
  return { text: message };
}

/**
 * Responds to a REMOVED_FROM_SPACE event in Hangouts Chat.
 * @param {object} event the event object from Hangouts Chat
 * @see https://developers.google.com/hangouts/chat/reference/message-formats/events
 */
function onRemoveFromSpace(event) {
  console.info(event);
  console.log('Bot removed from ', event.space.name);
}

Antes de executar e testar o bot, você precisa criar um novo projeto do Google Cloud Console, ativar a API Hangouts Chat e publicar seu bot na organização do G Suite.

Publique o seu bot

Antes de publicar seu bot no Hangouts Chat, você precisa primeiro atualizar o manifesto do script.

  1. No editor do Apps Script, clique em Exibir> Mostrar arquivo de manifesto .
  2. Adicione a linha "chat": {} ao seu arquivo de manifesto.

Seu arquivo de manifesto deve ser semelhante ao exemplo a seguir.

appsscript.json

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {
  },
  "chat": {}
}

Você também precisa criar um novo projeto do Google Cloud Console e atualizar o script para usá-lo.

  1. Crie um novo projeto no Google Cloud Developer Console. Dê um nome a ela, selecione uma conta de faturamento quando for solicitada e clique em CRIAR .
  2. Quando a criação do projeto for concluída, uma notificação aparecerá no canto superior direito da página. Clique na entrada Criar Projeto: <Nome do Projeto> para abrir o projeto.
  3. Clique no ícone do menu f5fbd278915eb7aa.png no canto superior esquerdo e navegue até APIs e serviços> Credenciais . Clique na guia da tela de consentimento do OAuth ( link direto ).
  4. No campo Nome do aplicativo, insira "Attendance Bot" e clique no botão Salvar na parte inferior.
  5. Clique no ícone de três pontos 50fa7e30ed2d1b1c.png no canto superior direito para expandir o menu e selecionar Configurações do projeto ( link direto ).
  6. Copie o valor listado em Número do projeto .
  7. De volta ao App Script Editor, clique em Resources> Cloud Platform project .
  8. Insira o número do projeto na caixa de texto e clique em Definir projeto . Quando solicitado, clique em Confirmar .
  9. Ao concluir, clique no botão Fechar ou no ícone X para fechar a caixa de diálogo.

Para publicar seu bot no Hangouts Chat, faça o seguinte:

  1. No editor do Apps Script, obtenha o ID de implantação do script clicando em Publicar> Implantar a partir do manifesto .
  2. Na caixa de diálogo Implantações , clique em Obter ID .
  3. Na caixa de diálogo ID de implantação , copie o valor listado para a ID de implantação . Clique em Fechar e Fechar para descartar as caixas de diálogo.
  4. No Google Cloud Console , clique em APIs e serviços> Biblioteca .
  5. Na Biblioteca, pesquise 'Hangouts Chat'. Selecione a API na lista de resultados.
  6. Na página da API Hangouts Chat, clique em Ativar . O Cloud Console exibe um indicador de progresso enquanto habilita a API.
  7. Depois que a API estiver ativada, na página API do Hangouts Chat , clique na guia Configuração . Observação: ignore todas as mensagens solicitando a criação de credenciais.
  8. Na guia Configuração , faça o seguinte:
  • Na caixa de nome do bot , digite 'Attendance Bot'.
  • Na caixa URL do avatar , digite 'https://goo.gl/kv2ENA'.
  • Na caixa Descrição , insira 'Apps Script codelab bot'.
  • Em Funcionalidade , selecione Bot funciona em mensagens diretas .
  • Em Configurações de conexão , selecione o projeto Apps Script e cole o ID de implantação do seu script na caixa de texto.
  • Em Permissões , selecione Pessoas e grupos específicos em seu domínio . Na caixa de texto abaixo do menu suspenso, digite seu endereço de e-mail associado à sua organização do G Suite.
  • Clique em Salvar alterações .

Depois de salvar suas alterações, verifique se o status na página da API Hangouts Chat mostra que o status do bot está AO VIVO - disponível para os usuários .

Teste o bot

Para testar seu bot no Hangouts Chat, faça o seguinte:

  1. Abra o Hangouts Chat .
  2. Clique em Encontrar pessoas, salas, bots> Enviar mensagem a um bot .
  3. Na lista, selecione o "Attendance Bot" que você criou.

Quando o tópico de mensagem direta abrir, você deverá ver uma mensagem do bot agradecendo por adicioná-lo a um DM, conforme mostrado na imagem a seguir.

22ea6d660d72eeca.png

Na etapa anterior, seu bot respondeu aos eventos do Hangouts Chat com uma resposta de texto simples. Nesta etapa, você atualizará seu bot para responder com cartões .

Respostas do cartão

O Hangouts Chat oferece suporte ao uso de cartões para respostas. Os cartões são recipientes visuais que permitem agrupar conjuntos de widgets de interface do usuário. Os cartões podem exibir cabeçalhos, parágrafos de texto, conjuntos de botões, imagens e texto de chave / valor. Seu bot pode definir um ou vários cartões em sua resposta JSON ao Hangouts Chat, que então traduz sua resposta nos elementos de IU correspondentes.

A imagem a seguir mostra uma resposta de cartão com três seções, que inclui um cabeçalho, um widget de chave / valor, um widget de imagem e um botão de texto.

b5a194ed8d745ba9.png

Para responder às mensagens do usuário com uma resposta de cartão, adicione o seguinte código ao arquivo Code.gs do seu bot.

Code.gs

var DEFAULT_IMAGE_URL = 'https://goo.gl/bMqzYS';
var HEADER = {
  header: {
    title : 'Attendance Bot',
    subtitle : 'Log your vacation time',
    imageUrl : DEFAULT_IMAGE_URL
  }
};

/**
 * Creates a card-formatted response.
 * @param {object} widgets the UI components to send
 * @return {object} JSON-formatted response
 */
function createCardResponse(widgets) {
  return {
    cards: [HEADER, {
      sections: [{
        widgets: widgets
      }]
    }]
  };
}

/**
 * Responds to a MESSAGE event triggered
 * in Hangouts Chat.
 *
 * @param event the event object from Hangouts Chat
 * @return JSON-formatted response
 */
function onMessage(event) {
  var userMessage = event.message.text;

  var widgets = [{
    "textParagraph": {
      "text": "You said: " + userMessage
    }
  }];

  return createCardResponse(widgets);
}

A função onMessage() , adicionada nesta etapa, lê a mensagem original do usuário e constrói uma resposta como um widget TextParagragh simples. A função onMessage() então chama createCardResponse() , que coloca o widget TextParagraph em uma seção de um único cartão. O bot retorna o objeto JavaScript construído com a resposta do cartão ao Hangouts Chat.

Teste o bot

Para testar este bot, basta voltar para sua mensagem direta com o bot no Hangouts Chat e digitar uma mensagem (qualquer mensagem servirá).

e12417d9aa7e177c.png

Observe que o manipulador de eventos onMessage() analisa o objeto de evento transmitido a ele pelo Hangouts Chat para extrair a mensagem original do usuário. Você também pode obter outros tipos de informações sobre o evento, incluindo o nome do usuário que iniciou o evento, seu endereço de e-mail, o nome da sala em que o evento ocorreu e muito mais.

Para obter mais informações sobre a estrutura dos objetos de evento enviados pelo Hangouts Chat, consulte a referência de formatos de evento .

Na etapa anterior, seu bot respondeu a uma mensagem de um usuário - um evento MESSAGE - com um cartão simples que continha um widget TextParagragh . Nesta etapa, você criará uma resposta que inclui botões, onde cada botão possui uma ação personalizada definida para ele.

Cartões interativos

As respostas do cartão podem conter um dos dois tipos de botões: widgets TextButton, que exibem botões somente de texto; e widgets ImageButton, que exibem um botão com um ícone simples ou imagem sem texto. Os widgets TextButton e ImageButton suportam um de dois comportamentos onClick (conforme definido na resposta JSON enviada de volta ao Hangouts Chat): openLink ou action . Como o nome indica, openLink abre um link especificado em uma nova guia do navegador.

O objeto de action , no entanto, especifica uma ação personalizada para o botão executar. Você pode especificar vários valores arbitrários no objeto de ação, incluindo um actionMethodName exclusivo e um conjunto de pares de parâmetros de chave / valor.

Especificar um objeto de action para o botão cria um cartão interativo . Quando o usuário clica no botão da mensagem, o Hangouts Chat gera um evento CARD_CLICKED e envia uma solicitação de volta ao bot que enviou a mensagem original. O bot, então, precisa lidar com o evento gerado no Hangouts Chat e retornar uma resposta ao espaço.

Substitua a função onMessage() em Code.gs com o código a seguir. Este código cria dois botões, um botão Definir férias no Gmail e um botão Bloquear dia no calendário no cartão enviado ao Hangouts Chat.

Code.gs

var REASON = {
  SICK: 'Out sick',
  OTHER: 'Out of office'
};
/**
 * Responds to a MESSAGE event triggered in Hangouts Chat.
 * @param {object} event the event object from Hangouts Chat
 * @return {object} JSON-formatted response
 */
function onMessage(event) {
  console.info(event);
  var reason = REASON.OTHER;
  var name = event.user.displayName;
  var userMessage = event.message.text;

  // If the user said that they were 'sick', adjust the image in the
  // header sent in response.
  if (userMessage.indexOf('sick') > -1) {
    // Hospital material icon
    HEADER.header.imageUrl = 'https://goo.gl/mnZ37b';
    reason = REASON.SICK;
  } else if (userMessage.indexOf('vacation') > -1) {
    // Spa material icon
    HEADER.header.imageUrl = 'https://goo.gl/EbgHuc';
  }

  var widgets = [{
    textParagraph: {
      text: 'Hello, ' + name + '.<br/>Are you taking time off today?'
    }
  }, {
    buttons: [{
      textButton: {
        text: 'Set vacation in Gmail',
        onClick: {
          action: {
            actionMethodName: 'turnOnAutoResponder',
            parameters: [{
              key: 'reason',
              value: reason
            }]
          }
        }
      }
    }, {
      textButton: {
        text: 'Block out day in Calendar',
        onClick: {
          action: {
            actionMethodName: 'blockOutCalendar',
            parameters: [{
              key: 'reason',
              value: reason
            }]
          }
        }
      }
    }]
  }];
  return createCardResponse(widgets);
}

Para lidar com o evento CARD_CLICKED , você precisa adicionar a função onCardClick() ao script do seu bot. Adicione o seguinte código que define a função o nCardClick() Code.gs

Code.gs

/**
 * Responds to a CARD_CLICKED event triggered in Hangouts Chat.
 * @param {object} event the event object from Hangouts Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/hangouts/chat/reference/message-formats/events
 */
function onCardClick(event) {
  console.info(event);
  var message = '';
  var reason = event.action.parameters[0].value;
  if (event.action.actionMethodName == 'turnOnAutoResponder') {
    turnOnAutoResponder(reason);
    message = 'Turned on vacation settings.';
  } else if (event.action.actionMethodName == 'blockOutCalendar') {
    blockOutCalendar(reason);
    message = 'Blocked out your calendar for the day.';
  } else {
    message = "I'm sorry; I'm not sure which button you clicked.";
  }
  return { text: message };
}

Ao responder aos cliques do usuário, agora o bot faz uma de duas coisas: configura a resposta automática de férias do usuário no Gmail para uma mensagem "fora do escritório"; ou agenda uma reunião de dia inteiro no Calendário do usuário. Para realizar essas tarefas, o bot chama o serviço avançado do Gmail e a API Calendar Apps Script .

Adicione o seguinte código ao seu script para integrar o bot ao Gmail e ao Agenda.

Code.gs

var ONE_DAY_MILLIS = 24 * 60 * 60 * 1000;
/**
 * Turns on the user's vacation response for today in Gmail.
 * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
 */
function turnOnAutoResponder(reason) {
  var currentTime = (new Date()).getTime();
  Gmail.Users.Settings.updateVacation({
    enableAutoReply: true,
    responseSubject: reason,
    responseBodyHtml: "I'm out of the office today; will be back on the next business day.<br><br><i>Created by Attendance Bot!</i>",
    restrictToContacts: true,
    restrictToDomain: true,
    startTime: currentTime,
    endTime: currentTime + ONE_DAY_MILLIS
  }, 'me');
}

/**
 * Places an all-day meeting on the user's Calendar.
 * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
 */
function blockOutCalendar(reason) {
  CalendarApp.createAllDayEvent(reason, new Date(), new Date(Date.now() + ONE_DAY_MILLIS));
}

Finalmente, você precisa habilitar o Gmail Advanced Service no projeto. Para ativar a API do Gmail, faça o seguinte:

  1. Clique em Recursos> Serviços avançados do Google .
  2. Na lista, encontre a API do Gmail e selecione em .
  3. Ainda na caixa de diálogo, clique no link Painel da API do Google Cloud Platform abaixo que abre o Console do Google Cloud .
  4. Clique em Ativar APIs e serviços .
  5. Pesquise 'Gmail API' e clique no cartão Gmail API.
  6. Na página API do Gmail , clique em Ativar .

Teste o bot

Para testar esta versão do seu bot, abra o DM que você iniciou nas etapas anteriores no Hangouts Chat e digite 'Estou doente'. O bot deve responder com um cartão semelhante à imagem abaixo.

Nota: Se você for solicitado a fornecer acesso ao bot, talvez seja necessário digitar sua mensagem uma segunda vez.

c0e8d9d0b5d0cf8b.png

Seu bot agora pode responder às mensagens do usuário, definir a resposta automática de férias no Gmail e colocar um evento de dia inteiro no calendário.

O que cobrimos

  • Criou um bot no Apps Script e publicou no Hangouts Chat
  • Respondeu às mensagens do usuário com uma resposta simples
  • Interagiu com outros serviços do G Suite em nome do usuário por meio do bot

Saber mais