Saia de férias com um app do Google Chat

1. Introdução

Os apps do Google Chat levam serviços e recursos diretamente para o Chat, onde os usuários obtêm informações e podem agir sem sair da conversa.

Neste codelab, você vai aprender a criar um app do Chat, o "Attendance Bot", que define respostas automáticas de férias no Gmail e agenda reuniões no Google Agenda. Ao criar o Attendance Bot no Google Apps Script, é possível acessar facilmente outros serviços do Google, como Drive, Gmail, Agenda, Documentos, Planilhas e muito mais.

O que você vai aprender

• Como adicionar manipuladores em eventos gerados no Chat
• Como analisar objetos de evento enviados pelo Chat
• Como responder ao Chat com mensagens no formato de fichas de informações
• Como definir e reagir a ações personalizadas para cliques em botões nas fichas de informações

O que é necessário

• Acesso à Internet e a um navegador da Web.
• Uma conta do Google Workspace com acesso ao Google Chat.
• Habilidades básicas de JavaScript. O Google Apps Script aceita somente JavaScript.

Aviso: use uma conta do Google Workspace para concluir este codelab. Usar uma conta @gmail.com resulta em erro ao tentar ativar a API.

2. Faça o download do exemplo de código

É possível fazer o download de um arquivo ZIP ou clonar o repositório do GitHub para exibir o código de cada etapa deste exemplo.

As pastas step-NN contêm o estado final desejado de cada etapa deste codelab. Elas servem como referência.

Faça o download do código

Para fazer o download do código para este codelab, clique neste botão:

Download do código-fonte

Descompacte o arquivo ZIP transferido por download. Isso descompacta uma pasta-raiz (hangouts-chat-apps-script-codelab) que contém uma pasta para cada etapa deste codelab.

Clone o repositório do GitHub

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

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

3. Crie os manipuladores para eventos do Google Chat

Crie um projeto do Apps Script

Para criar um projeto do Apps Script, siga as seguintes etapas:

1. Acesse script.new.
2. Clique em Projeto sem título.
3. Renomeie o script como Attendance Bot e clique em Renomear.

Eventos do Google Chat

A maioria das interações do Apps Script com o Chat é orientada por eventos. A interação entre o usuário, o app do Chat e o Chat normalmente segue esta sequência:

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

O Chat gera 4 eventos que o app pode detectar:

• ADDED_TO_SPACE: ocorre quando um usuário humano adiciona um app do Chat a um espaço ou uma mensagem direta (DM). No Apps Script, defina uma função onAddToSpace() para processar esse evento.
• REMOVED_FROM_SPACE: ocorre quando um usuário remove o app do Chat de um espaço ou de uma mensagem direta. Esse evento não envia uma resposta de volta ao Chat. No Apps Script, defina uma função onRemoveFromSpace() para processar esse evento.
• MESSAGE: ocorre quando um usuário envia uma mensagem ao app do Chat como mensagem direta ou como uma @menção em um espaço. No Apps Script, defina uma função onMessage() para responder a esse evento.
• CARD_CLICKED: ocorre quando o usuário clica em um botão com uma ação personalizada atribuída. No Apps Script, defina uma função onCardClick() para responder a esse evento.

Substitua o conteúdo do arquivo Code.gs pelo código a seguir que define manipuladores para os eventos ADDED_TO_SPACE e REMOVE_FROM_SPACE. Você vai adicionar manipuladores para os eventos MESSAGE e CARD_CLICKED posteriormente neste codelab.

Code.gs

/**
 * Responds to an ADDED_TO_SPACE event in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/chat/api/guides/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 Google Chat.
 * @param {object} event the event object from Google Chat
 * @see https://developers.google.com/chat/api/guides/message-formats/events
 */
function onRemoveFromSpace(event) {
  console.info(event);
  console.log('Chat app removed from ', event.space.name);
}

4. Publique e teste o app do Chat

Atualize o arquivo de manifesto do script

Antes de publicar seu app no Chat, atualize o manifesto do script.

1. Clique em Configurações do projeto.
2. Selecione a caixa de seleção Mostrar arquivo de manifesto "appsscript.json" no editor.
3. Clique em Editor .
4. Clique no arquivo appsscript.json.
5. Adicione a linha "chat": {} ao arquivo do manifesto.

O arquivo do manifesto será parecido com o exemplo a seguir.

appsscript.json

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

Crie um projeto do Google Cloud

Antes de executar e testar o app do Chat, crie um projeto do Google Cloud, ative e configure a API Chat e publique seu app do Chat na organização do Google Workspace.

Observação: se você estiver executando este codelab de um quiosque em um evento hospedado pelo Google, um projeto do Google Cloud Console já foi criado para você. Abra o projeto e pule para o item 3 da lista a seguir.

1. No console do Google Cloud, acesse Menu > IAM e administrador > Criar um projeto.
   Criar um projeto
   
2. Insira um nome descritivo em Nome do projeto.
3. Se solicitado, selecione Organização e Conta de faturamento.
4. Clique em Criar.
5. Quando a criação do projeto é concluída, uma notificação aparece no canto superior direito da página. Clique na entrada Criar projeto: <Nome do projeto> para abri-lo.
6. Clique em Menu > APIs e serviços > Credenciais.
7. Clique na Tela de permissão OAuth.
8. Digite Attendance Bot no Nome do app.
9. Se solicitado, insira o e-mail de suporte ao usuário e as informações de contato do desenvolvedor.
10. Clique em Salvar e continuar.
11. Clique em Configurações e utilitários > Configurações do projeto.
12. Copie o Número do projeto.
13. Volte ao editor do App Script e clique em Configurações do projeto .
14. Em Projeto do Google Cloud Platform (GCP), clique em Mudar projeto.
15. Clique em Número do projeto do GCP e insira o número do projeto.
16. Clique em Configurar projeto.

Publique o app no Chat

Para publicar seu app no Google Chat, faça o seguinte:

1. No editor do Apps Script, clique em Implantar > Nova implantação.
2. Ao lado de Selecionar tipo, clique em Habilitar tipos de implantação .
3. Selecione Complemento e clique em Implantar.
4. Copie o ID da implantação e clique em Concluído.
5. No console do Google Cloud, acesse Menu > APIs e serviços > Biblioteca.
   Acessar a biblioteca
   
6. Pesquise a API Google Chat. Selecione a API na lista de resultados.
7. Na página da API Google Chat, clique em Ativar.
8. Depois de ativar a API, clique em Configuração. Ignore todas as mensagens que solicitam a criação de credenciais.
9. Na página Configuração, faça o seguinte:

• Digite Attendance Bot no Nome do app.
• Digite https://goo.gl/kv2ENA no URL do avatar.
• Digite App do Chat do codelab do Apps Script na Descrição.
• Em Funcionalidade, selecione Receber mensagens uma a uma.
• Em Configurações de conexão, selecione Projeto do 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 de seu domínio. Na caixa de texto do menu suspenso, digite o endereço de e-mail associado à organização do Google Workspace.
• Clique em Salvar.

Observação: se você tenta ativar a API Google Chat com uma conta @gmail.com, recebe o erro:

A API "chat.googleapis.com" não existe ou você não tem permissão para acessá-la

Você precisa se conectar com uma conta do Google Workspace e/ou usar o seletor de contas no canto superior direito do console do Cloud para mudar para uma conta do Google Workspace. Se você criou o script com uma conta @gmail.com, é necessário compartilhá-lo com sua conta do Google Workspace.

Depois de salvar as alterações, verifique se o status na página da API Google Chat mostra o Status do app como Ao vivo: disponível para os usuários.

Teste o app do Chat

Para testar o app no Google Chat, faça o seguinte:

1. Abra o Google Chat.
2. Clique em Iniciar uma conversa > Encontrar apps para enviar uma mensagem direta nova para o app do Chat.
3. Na página "Encontrar apps", pesquise Attendance Bot.
4. Ao lado de Attendance Bot, clique em Adicionar > Chat.

Quando o grupo de mensagens diretas é aberto, você vê uma mensagem do app do Chat agradecendo por adicioná-lo a uma mensagem direta, como mostra a imagem abaixo.

Observação: o código deste app do Chat registra os objetos de evento recebidos do Google Chat. Consulte os registros para conferir a estrutura dos objetos de evento. Para abrir os registros, clique em Visualizar > Stackdriver Logging no editor do Apps Script.

5. Defina uma resposta em formato de ficha de informações

Na etapa anterior, o app respondeu aos eventos do Google Chat com uma resposta de texto simples. Nesta etapa, você vai atualizar o app para responder com fichas de informações.

Respostas em fichas de informações

O Google Chat é compatível com o uso de fichas de informações para respostas. Fichas de informações são contêineres visuais que permitem agrupar conjuntos de widgets da interface do usuário. As fichas de informações podem exibir cabeçalhos, parágrafos de texto, conjuntos de botões, imagens e texto de chave-valor. O app pode definir uma ou mais fichas de informações na resposta JSON para o Google Chat, que transforma a resposta nos elementos correspondentes da interface.

A imagem abaixo mostra uma resposta em ficha de informações com três seções, como um cabeçalho, um widget de chave-valor, um widget de imagem e um botão de texto.

Para responder às mensagens do usuário com uma resposta em ficha de informações, adicione o código a seguir ao arquivo Code.gs do app do Chat.

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 Google Chat.
 *
 * @param event the event object from Google 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 cria uma resposta como um widget TextParagragh simples. A função onMessage() chama createCardResponse(), que coloca o widget TextParagraph em uma seção de uma única ficha de informações. O bot envia o objeto JavaScript criado com a resposta em ficha de informações de volta para o Google Chat.

Teste o app do Chat

Para testar o app, volte para a mensagem direta com o app no Google Chat e digite uma mensagem. Qualquer mensagem serve.

O manipulador de eventos onMessage() analisa o objeto do evento enviado pelo Google Chat para extrair a mensagem original do usuário. Também é possível exibir outras informações sobre o evento, como o nome e o endereço de e-mail do usuário que o iniciou, o nome do espaço onde o evento ocorreu e muito mais.

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

6. Reações a cliques em botões nas fichas de informações

Na etapa anterior, o app do Chat respondeu a uma mensagem do usuário (um evento MESSAGE) com uma ficha de informações simples contendo um widget TextParagragh. Nesta etapa, você vai criar uma resposta que inclui botões com ações personalizadas definidas.

Fichas de informações interativas

As respostas em ficha de informações podem conter um destes dois botões: widgets TextButton, que exibem botões de texto somente, e widgets ImageButton, que exibem um botão com um ícone simples ou uma imagem sem texto. Os widgets TextButton e ImageButton aceitam os dois comportamentos onClick, conforme definido na resposta JSON enviada de volta para o Google Chat: openLink ou action. Como o nome indica, openLink abre um determinado link em uma nova guia do navegador.

O objeto action especifica uma ação personalizada para o botão executar. É possível definir diversos valores arbitrários nesse objeto de ação, como um actionMethodName exclusivo e um conjunto de pares de parâmetros de chave-valor.

Especificar um objeto action para o botão cria uma ficha de informações interativa. Quando o usuário clica no botão da mensagem, o Google Chat gera um evento CARD_CLICKED e retorna uma solicitação ao app que enviou a mensagem original. Em seguida, o app precisa processar o evento gerado no Google Chat e retornar uma resposta ao espaço.

Substitua a função onMessage() em Code.gs pelo código a seguir. Esse código cria dois botões na ficha de informações enviada para o Google Chat: Definir férias no Gmail e Bloquear dia no Agenda.

Code.gs

var REASON = {
  SICK: 'Out sick',
  OTHER: 'Out of office'
};
/**
 * Responds to a MESSAGE event triggered in Google Chat.
 * @param {object} event the event object from Google 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 processar o evento CARD_CLICKED, adicione a função onCardClick() ao script do app do Chat. Adicione o código a seguir, que define a função onCardClick() Code.gs.

Code.gs

/**
 * Responds to a CARD_CLICKED event triggered in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/chat/api/guides/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 };
}

Em resposta aos cliques do usuário, o app do Chat realiza uma das seguintes ações: define a resposta automática de férias no Gmail como "fora do escritório" ou programa uma reunião de dia inteiro no Agenda. Para isso, o app chama o serviço avançado do Gmail e o serviço do Agenda.

Adicione o código a seguir ao script para integrar o app do Chat 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));
}

Por fim, habilite o serviço avançado do Gmail no projeto. Para ativar a API Gmail, faça o seguinte:

1. No editor do Apps Script, ao lado de Serviços, clique em "Adicionar um serviço" .
2. Selecione a API Gmail.
3. Clique em Painel da API Google Cloud Platform para abrir o console do Google Cloud.
4. Clique em Ativar APIs e serviços.
5. Pesquise por API Gmail e clique nela.
6. Na página da API Gmail, clique em Ativar.

Teste o app do Chat

Para testar esta versão do app do Chat, abra a mensagem direta que você iniciou nas etapas anteriores no Google Chat e digite estou de férias. O app responderá com uma ficha de informações semelhante à imagem abaixo.

Observação: se você precisar fornecer acesso ao app, talvez seja necessário digitar a mensagem novamente.

7. Parabéns!

Agora seu app do Chat pode responder às mensagens dos usuários, definir respostas automáticas de férias no Gmail e criar um evento de dia inteiro no Agenda.

O que aprendemos

• Criamos e publicamos um app do Google Chat com o Apps Script
• Enviamos respostas simples às mensagens do usuário
• Interagimos com outros serviços do Google Workspace em nome do usuário por meio do app do Chat

Saiba mais

• Site da documentação do Google Chat
• Guia de início rápido do app do Chat com o Apps Script
• Crie apps do Chat
• Publique apps do Chat
• Crie fichas de informações interativas
• Referência de fichas de informações
• Referência de objetos de evento
• Referência do serviço avançado do Gmail
• Referência do serviço Agenda