Coletar e gerenciar contatos no Google Chat

Este tutorial mostra como criar um app do Google Chat que ajuda os usuários a gerenciar contatos pessoais e profissionais. Para coletar do usuário, o app do Chat solicita que os usuários concluam um formulário de contato nas mensagens e caixas de diálogo do card.

Confira o app Chat em ação:

Pré-requisitos

• Uma empresa Conta do Google Workspace com acesso a Google Chat.

Objetivos

• Projetar e criar interfaces do usuário (IUs) como objetos card e exibir as interfaces em mensagens e caixas de diálogo.
• Receber e processar informações que os usuários enviam usando widgets de entrada de formulário.
• Responda a comandos de barra enviando mensagens que contêm texto, cards e widgets de acessórios.

Arquitetura

O app do Chat é integrado Google Apps Script e usos eventos de interação para processar e responder aos usuários do Chat.

Veja a seguir como um usuário normalmente pode interagir com o App do Chat:

1. um usuário abrir uma mensagem direta com o app do Chat; ou adiciona o app do Chat a um espaço existente.

2. O app de chat pede ao usuário para adicionar um contato criando e mostrando um formulário de contato como um objeto card. Para apresentar o formulário de contato, o app do Chat responde aos usuários das seguintes maneiras:

   • Responde a @menções e mensagens diretas com uma mensagem de card que contém o formulário de contato.
   • Responde ao comando de barra /addContact abrindo uma caixa de diálogo com o formulário de contato.
   • Responde ao comando de barra /about com uma mensagem de texto que tem Adicionar um contato no qual os usuários podem clicar para abrir uma caixa de diálogo com o formulário de contato.

3. Quando o formulário de contato é apresentado, o usuário insere as informações de contato nos seguintes campos e widgets:

   • Nome e sobrenome: um textInput que aceita strings.
   • Data de nascimento: um dateTimePicker que aceita apenas datas.
   • Tipo de contato: um widget de selectionInput botões de opção que permite que os usuários selecionem e enviem um único valor de string (Personal ou Work).
   • Botão Revisar e enviar: um buttonList matriz com o widget button no qual o usuário clica para enviar os valores que que eles inserem.

4. O app Google Chat processa um evento de interação CARD_CLICKED para processar os valores inseridos pelo usuário e os exibe em um card de confirmação.

5. O usuário revisa o cartão de confirmação e clica no botão Enviar. para finalizar os dados de contato.

6. O app Google Chat envia uma mensagem de texto particular que confirma o envio.

Prepare o ambiente

Esta seção mostra como criar e configurar um projeto do Google Cloud para o app Chat.

Criar um projeto do Google Cloud

Console do Google Cloud

1. No console do Google Cloud, acesse Menu menu > IAM e administrador > Criar um projeto.

   Acessar "Criar um projeto"

2. No campo Nome do projeto, insira um nome descritivo.

   Opcional: para editar o ID do projeto, clique em Editar. O ID do projeto não pode ser alterado após a criação do projeto, então escolha um ID que atenda às suas necessidades para o ciclo de vida projeto.

3. No campo Local, clique em Procurar para mostrar os possíveis locais para sua projeto. Em seguida, clique em Selecionar.
4. Clique em Criar. O console do Google Cloud navega até a página "Painel", e seu projeto é criado em alguns minutos.

CLI da gcloud

Em um dos ambientes de desenvolvimento a seguir, acesse o Google Cloud CLI (gcloud):

• Cloud Shell: para usar um terminal on-line com a gcloud CLI configure o Cloud Shell.
  Ativar o Cloud Shell
• Local Shell: para usar um ambiente de desenvolvimento local, instalar e inicializar a CLI gcloud.
  Para criar um projeto do Cloud, use o comando gcloud projects create:

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID definindo o ID do projeto que você quer criar.

Configurar a autenticação e a autorização

Os apps do Google Chat exigem que você configure uma Tela de consentimento OAuth para que os usuários podem autorizar seu app nos aplicativos do Google Workspace, incluindo Google Chat

Neste tutorial, você implanta um app de chat apenas para testes e uso interno. Portanto, é possível usar informações de marcador de posição para a tela de consentimento. Antes de publicar o app Chat, substitua as informações de marcador de posição por informações reais.

1. No console do Google Cloud, acesse Cardápio menu > APIs e Serviços > Tela de permissão OAuth.

   Acessar a tela de permissão OAuth

2. Em Tipo de usuário, selecione Interno e clique em Criar.

3. Em Nome do app, digite Contact Manager.

4. Em E-mail para suporte do usuário, selecione seu endereço de e-mail ou uma grupo do Google.

5. Em Dados de contato do desenvolvedor, insira seu endereço de e-mail.

6. Clique em Salvar e continuar.

7. Na página Escopos, clique em Salvar e continuar. O O app do Chat não requer escopos OAuth.

8. Leia o resumo e clique em Voltar ao painel.

Criar e implantar o app do Chat

Na seção a seguir, você vai copiar e atualizar um Projeto do Apps Script que contém todos os aplicativos necessários para o app do Chat. Por isso, não é necessário copiar e e colar cada arquivo.

Outra opção é acessar o projeto inteiro no GitHub.

Ver no GitHub

Esta é uma visão geral de cada arquivo:

main.gs

Processa toda a lógica do app, incluindo eventos de interação sobre quando os usuários enviam mensagens para o app Chat, clicam em botões de uma mensagem do app Chat ou abrem e fecham caixas de diálogo.

Mostrar código main.gs

apps-script/contact-form-app/main.gs

Ver no GitHub

/**
 * Copyright 2024 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * Responds to a MESSAGE interaction event in Google Chat.
 *
 * @param {Object} event the MESSAGE interaction event from Chat API.
 * @return {Object} message response that opens a dialog or sends private
 *                          message with text and card.
 */
function onMessage(event) {
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case 1:
        // If the slash command is "/about", responds with a text message and button
        // that opens a dialog.
        return {
          text: "Manage your personal and business contacts 📇. To add a " +
                  "contact, use the slash command `/addContact`.",
          accessoryWidgets: [{ buttonList: { buttons: [{
            text: "Add Contact",
            onClick: { action: {
              function: "openDialog",
              interaction: "OPEN_DIALOG"
            }}
          }]}}]
        }
      case 2:
        // If the slash command is "/addContact", opens a dialog.
        return openDialog(event);
    }
  }

  // If user sends the Chat app a message without a slash command, the app responds
  // privately with a text and card to add a contact.
  return {
    privateMessageViewer: event.user,
    text: "To add a contact, try `/addContact` or complete the form below:",
    cardsV2: [{
      cardId: "addContactForm",
      card: {
        header: { title: "Add a contact" },
        sections:[{ widgets: CONTACT_FORM_WIDGETS.concat([{
          buttonList: { buttons: [{
            text: "Review and submit",
            onClick: { action: { function : "openNextCard" }}
          }]}
        }])}]
      }
    }]
  };
}

/**
 * Responds to CARD_CLICKED interaction events in Google Chat.
 *
 * @param {Object} event the CARD_CLICKED interaction event from Google Chat.
 * @return {Object} message responses specific to the dialog handling.
 */
function onCardClick(event) {
  // Initial dialog form page
  if (event.common.invokedFunction === "openDialog") {
    return openDialog(event);
  // Second dialog form page
  } else if (event.common.invokedFunction === "openNextCard") {
    return openNextCard(
      event.user,
      fetchFormValue(event, "contactName"),
      fetchFormValue(event, "contactBirthdate"),
      fetchFormValue(event, "contactType"),
      event.isDialogEvent
    );
  // Dialog form submission
  } else if (event.common.invokedFunction === "submitForm") {
    const userInputs = event.common.parameters;
    return submitForm(event.user, userInputs, event.dialogEventType);
  }
}

/**
 * Extracts form input value for a given widget.
 *
 * @param {Object} event the CARD_CLICKED interaction event from Google Chat.
 * @param {String} widgetName a unique ID for the widget, specified in the widget's name field.
 * @returns the value inputted by the user, null if no value can be found.
 */
function fetchFormValue(event, widgetName) {
  const formItem = event.common.formInputs[widgetName][""];
  // For widgets that receive StringInputs data, the value input by the user.
  if (formItem.hasOwnProperty("stringInputs")) {
    const stringInput = event.common.formInputs[widgetName][""].stringInputs.value[0];
    if (stringInput != null) {
      return stringInput;
    }
  // For widgets that receive dateInput data, the value input by the user.
  } else if (formItem.hasOwnProperty("dateInput")) {
    const dateInput = event.common.formInputs[widgetName][""].dateInput.msSinceEpoch;
     if (dateInput != null) {
       return dateInput;
     }
  }

  return null;
}

/**
 * Opens a dialog that prompts users to add details about a contact.
 *
 * @return {Object} a message with an action response to open a dialog.
 */
function openDialog() {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { dialog: { body: { sections: [{
      header: "Add new contact",
      widgets: CONTACT_FORM_WIDGETS.concat([{
        buttonList: { buttons: [{
          text: "Review and submit",
          onClick: { action: { function: "openNextCard" }}
        }]}
      }])
    }]}}}
  }};
}

/**
 * Returns a dialog or card message that displays a confirmation of contact
 * details before users submit.
 *
 * @param {String} user the user who submitted the information.
 * @param {String} contactName the contact name from the previous dialog or card.
 * @param {String} contactBirthdate the birthdate from the previous dialog or card.
 * @param {String} contactType the contact type from the previous dialog or card.
 * @param {boolean} fromDialog whether the information was submitted from a dialog.
 *
 * @return {Object} returns a dialog or private card message.
 */
function openNextCard(user, contactName, contactBirthdate, contactType, fromDialog) {
  const name = contactName ?? "<i>Not provided</i>";
  const birthdate = contactBirthdate ?? "<i>Not provided</i>";
  const type = contactType ?? "<i>Not provided</i>";
  const cardConfirmation = {
    header: "Your contact",
    widgets: [{
      textParagraph: { text: "Confirm contact information and submit:" }}, {
      textParagraph: { text: "<b>Name:</b> " + name }}, {
      textParagraph: {
        text: "<b>Birthday:</b> " + convertMillisToDateString(birthdate)
      }}, {
      textParagraph: { text: "<b>Type:</b> " + type }}, {
      buttonList: { buttons: [{
        text: "Submit",
        onClick: { action: {
          function: "submitForm",
          parameters: [{
            key: "contactName", value: name }, {
            key: "contactBirthdate", value: birthdate }, {
            key: "contactType", value: type
          }]
        }}
      }]}
    }]
  };

  // Returns a dialog with contact information that the user input.
  if (fromDialog) {
    return { action_response: {
      type: "DIALOG",
      dialogAction: { dialog: { body: { sections: [ cardConfirmation ]}}}
    }};
  }

  // Updates existing card message with contact information that the user input.
  return {
    actionResponse: { type: "UPDATE_MESSAGE" },
    privateMessageViewer: user,
    cardsV2: [{
      card: { sections: [cardConfirmation]}
    }]
  }
}

/**
  * Submits information from a dialog or card message.
  *
  * @param {Object} user the person who submitted the information.
  * @param {Object} userInputs the form input values from event parameters.
  * @param {boolean} dialogEventType "SUBMIT_DIALOG" if from a dialog.
  * @return {Object} a message response that opens a dialog or posts a private
  *                  message.
  */
function submitForm(user, userInputs, dialogEventType) {
  const contactName = userInputs["contactName"];
  // Checks to make sure the user entered a contact name.
  // If no name value detected, returns an error message.
  if (!contactName) {
    const errorMessage = "Don't forget to name your new contact!";
    if (dialogEventType === "SUBMIT_DIALOG") {
      return { actionResponse: {
        type: "DIALOG",
        dialogAction: { actionStatus: {
          statusCode: "INVALID_ARGUMENT",
          userFacingMessage: errorMessage
        }}
      }};
    } else {
      return {
        privateMessageViewer: user,
        text: errorMessage
      };
    }
  }

  // The Chat app indicates that it received form data from the dialog or card.
  // Sends private text message that confirms submission.
  const confirmationMessage = "✅ " + contactName + " has been added to your contacts.";
  if (dialogEventType === "SUBMIT_DIALOG") {
    return {
      actionResponse: {
        type: "NEW_MESSAGE",
        dialogAction: { actionStatus: {
          statusCode: "OK",
          userFacingMessage: "Success " + JSON.stringify(contactName)
        }}
      },
      privateMessageViewer: user,
      text: confirmationMessage
    }
  } else {
    return {
      actionResponse: { type: "NEW_MESSAGE" },
      privateMessageViewer: user,
      text: confirmationMessage
    };
  }
}

/**
 * Converts date in milliseconds since epoch to user-friendly string.
 *
 * @param {Object} millis the milliseconds since epoch time.
 * @return {string} Display-friend date (English US).
 */
function convertMillisToDateString(millis) {
  const date = new Date(millis);
  const options = { year: 'numeric', month: 'long', day: 'numeric' };
  return date.toLocaleDateString('en-US', options);
}

contactForm.gs

Contém os widgets que recebem dados de formulário dos usuários. Essas entradas de formulário os widgets são exibidos em cards que aparecem em mensagens e caixas de diálogo.

Ver código do app contactForm.gs

apps-script/contact-form-app/contactForm.gs

Ver no GitHub

/**
 * Copyright 2024 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": false
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": false
        }
      ]
    }
  }
];

appsscript.json

O Manifesto do Apps Script que define e configura o projeto do Apps Script para a App Chat.

Mostrar código appsscript.json

apps-script/contact-form-app/appsscript.json

Ver no GitHub

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "chat": {}
}

Encontrar o número e o ID do projeto do Cloud

1. No console do Google Cloud, acesse seu projeto do Cloud.

   Acessar o Console do Google Cloud

2. Clique em "Configurações e utilitários" more_vert > Configurações do projeto.

3. Anote os valores nos campos Número do projeto e ID do projeto. Você vai usá-los nas seções a seguir.

Criar o projeto do Apps Script

Para criar um projeto do Apps Script e conectá-lo à sua Projeto do Google Cloud:

1. Clique no botão a seguir para abrir o projeto Gerenciar contatos no Google Chat do Apps Script.
   Abrir o projeto.
2. Clique em info_outline Overview.
3. Na página de visão geral, clique em Fazer uma cópia.

4. Nomeie sua cópia do projeto do Apps Script:

   1. Clique em Cópia de "Gerenciar contatos no Google Chat".

   2. Em Título do projeto, digite Contact Manager - Google Chat app.

   3. Clique em Renomear.

Definir o projeto do Cloud do projeto do Apps Script

1. No seu projeto do Apps Script, Clique em Configurações do projeto.
2. Em Projeto do Google Cloud Platform (GCP), clique em Mudar projeto.
3. Em Número do projeto do GCP, cole o número do seu projeto do Cloud.
4. Clique em Configurar projeto. O projeto do Cloud e do Apps Script agora estão conectados.

Criar uma implantação do Apps Script

Agora que todo o código está no lugar, implante o Apps Script projeto. Use o ID de implantação ao configurar o app Chat no Google Cloud.

1. No Apps Script, abra o projeto do app Chat.

   Acessar o Apps Script

2. Clique em Implantar > Nova implantação.

3. Se o Complemento ainda não estiver selecionado, ao lado de Selecionar tipo, clique nos tipos de implantação e selecione Complemento.

4. Em Descrição, digite uma descrição para essa versão, como Test of Contact Manager

5. Clique em Implantar. Relatórios do Apps Script concluídos e fornece um ID de implantação.

6. Clique em content_copy Copiar para copiar. o ID de implantação e clique em Concluído.

Configurar o app do Chat no console do Google Cloud

Esta seção mostra como configurar a API Google Chat no console do Google Cloud com informações sobre o app do Chat, incluindo ID da implantação que você acabou de criar a partir do seu Apps Script projeto.

1. No console do Google Cloud, clique em Menu menu > Mais produtos > Google Workspace > Biblioteca de produtos > API Google Chat > Gerenciar > Configuração.

   Acessar a configuração da API Chat

2. Em Nome do app, digite Contact Manager.

3. No URL do avatar, digite https://developers.google.com/chat/images/contact-icon.png.

4. Em Descrição, digite Manage your personal and business contacts.

5. Clique no botão Ativar recursos interativos para ativar a opção.

6. Em Funcionalidade, marque as caixas de seleção Receber mensagens individuais e Participar de espaços e conversas em grupo

7. Em Configurações de conexão, selecione Apps Script.

8. Em Deployment ID, cole o ID de implantação do Apps Script que você copiou na seção anterior, ao criar o implantação do Apps Script.

9. Em Comandos de barra, configure os comandos de barra /about e /addContact:

   1. Clique em Adicionar um comando de barra para configurar o primeiro comando de barra.
   2. Em Nome, digite /about.
   3. Em ID do comando, digite 1.
   4. Em Descrição, digite Learn how to use this Chat app to manage your contacts
   5. Selecione Abre uma caixa de diálogo.
   6. Clique em Concluído.
   7. Clique em Adicionar um comando de barra para configurar outro comando.
   8. Em Nome, digite /addContact
   9. Em ID do comando, digite 2.
   10. Em Descrição, digite Submit information about a contact
   11. Selecione Abre uma caixa de diálogo.
   12. Clique em Concluído.

10. Em Visibilidade, selecione o Disponibilize este app do Chat para pessoas e grupos específicos na caixa de seleção YOUR DOMAIN e digite seu endereço de e-mail.

11. Em Registros, selecione Registrar erros no Logging.

12. Clique em Salvar. Uma mensagem de configuração salva vai aparecer.

O app do Chat está pronto para ser instalado e testado Conversar.

Teste o app do Chat

Para testar seu app do Chat, abra um espaço de mensagem direta com do app do Chat e enviar uma mensagem:

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 add Nova conversa.
3. No campo Adicionar uma ou mais pessoas, digite o nome da sua App Chat.

4. Selecione o app Chat nos resultados. Um direto a mensagem será aberta.

1. Na nova mensagem direta com o app do Chat, Digite /addContact e pressione Enter.

2. Na caixa de diálogo exibida, insira os dados de contato:

   1. No campo de texto Nome e sobrenome, digite um nome.
   2. No seletor de data em Data de nascimento, escolha uma opção.
   3. Em Tipo de contato, selecione o botão de opção Trabalho ou Pessoal.

3. Clique em Revisar e enviar.

4. Na caixa de diálogo de confirmação, revise as informações enviadas e clique em Enviar. O app do Chat responde com um texto que diz ✅ CONTACT NAME has been added to your contacts.:

5. Também é possível testar e enviar o formulário de contato das seguintes maneiras:

   • Use o comando de barra /about. O app de chat responde com uma mensagem de texto e um botão de widget de acessório que diz Add a contact. Clique no botão para abrir uma caixa de diálogo com o formulário de contato.
   • Envie uma mensagem direta ao app Chat sem um comando de barra, como Hello. O app do Chat as respostas com um texto e um card que contêm o formulário de contato.

Limpar

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

1. No console do Google Cloud, acesse a página Gerenciar recursos. Clique em Cardápio menu > IAM e Administrador > Gerenciar recursos.

   Acessar o Resource Manager

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

Temas relacionados

• Responder a comandos de barra
• Coletar e processar informações dos usuários do Google Chat
• Abrir caixas de diálogo interativas
• Conheça outros exemplos de apps do Google Chat