Coletar e processar informações dos usuários do Google Chat

Este guia descreve como os apps do Google Chat podem coletar e processar informações dos usuários criando entradas de formulário em interfaces baseadas em cards.

No Google Chat, os complementos aparecem para os usuários como apps do Google Chat. Para saber mais, consulte a Visão geral do Extend Google Chat.

Os apps de chat solicitam informações dos usuários para realizar ações dentro ou fora do Chat, incluindo as seguintes:

• Defina as configurações. Por exemplo, para permitir que os usuários personalizem as configurações de notificação ou configurem e adicionem o app Chat a um ou mais espaços.
• Crie ou atualize informações em outros aplicativos do Google Workspace. Por exemplo, permita que os usuários criem um evento do Google Agenda.
• Permitir que os usuários acessem e atualizem recursos em outros apps ou serviços da Web. Por exemplo, um app de chat pode ajudar os usuários a atualizar o status de um tíquete de suporte diretamente em um espaço do Chat.

Pré-requisitos

Criar formulários usando cards

Para coletar informações, os apps do Chat projetam formulários e entradas e os criam em cards. Para mostrar cards aos usuários, os apps do Chat podem usar as seguintes interfaces:

• Mensagens de chat que contêm um ou mais cards.
• Caixas de diálogo, que são cards que são abertos em uma nova janela de mensagens e páginas iniciais.

Os apps de chat podem criar cards usando os seguintes widgets:

• Widgets de entrada de formulário que solicitam informações dos usuários. Opcionalmente, você pode adicionar validação a widgets de entrada de formulário para garantir que os usuários insiram e formatem as informações corretamente. Os apps de chat podem usar os seguintes widgets de entrada de formulário:

  • Entradas de texto (textInput) para texto livre ou sugerido.

  • As entradas de seleção (selectionInput) são elementos de interface selecionáveis, como caixas de seleção, botões de opção e menus suspensos. Os widgets de entrada de seleção também podem preencher e sugerir itens de dados do Google Workspace (como um espaço de chat) ou de uma fonte de dados dinâmica. Para saber mais, consulte a seção Adicionar um menu de múltipla seleção.

  • Seletores de data e hora (dateTimePicker) para entradas de data e hora.

• Um widget de botão para que os usuários possam enviar valores inseridos no card. Depois que um usuário clica no botão, o app de chat pode processar as informações recebidas.

No exemplo abaixo, um card coleta informações de contato usando um campo de texto, um seletor de data e hora e um campo de seleção:

Para mais exemplos de widgets interativos que podem ser usados para coletar informações, consulte Criar um card ou uma caixa de diálogo interativa na documentação da API Google Chat.

Adicionar um menu de seleção múltipla

Para personalizar itens de seleção ou permitir que os usuários selecionem itens de uma fonte de dados dinâmica, os apps de chat podem usar menus de seleção múltipla, que são um tipo de widget SelectionInput. Por exemplo, o card a seguir mostra um menu de seleção múltipla em que os usuários podem selecionar dinamicamente uma lista de contatos:

É possível preencher itens de um menu de múltipla seleção com as seguintes fontes de dados:

• Dados do Google Workspace, que incluem usuários ou espaços do Chat em que o usuário é membro. O menu só preenche itens da mesma organização do Google Workspace.
• Fontes de dados externas, como um banco de dados relacional. Por exemplo, é possível usar menus de múltipla seleção para ajudar um usuário a selecionar uma lista de leads de vendas de um sistema de gestão de relacionamento com o cliente (CRM).

Preencher itens de uma fonte de dados do Google Workspace

Para usar as origens de dados do Google Workspace, especifique o campo platformDataSource no widget SelectionInput. Ao contrário de outros tipos de entrada de seleção, você omite objetos SelectionItem, porque esses itens de seleção são fornecidos dinamicamente pelo Google Workspace.

O código a seguir mostra um menu de múltipla seleção de usuários do Google Workspace. Para preencher os usuários, a entrada de seleção define commonDataSource como USER:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

O código a seguir mostra um menu de seleção múltipla de espaços de chat. Para preencher espaços, a entrada de seleção especifica o campo hostAppDataSource. O menu de seleção múltipla também define defaultToCurrentSpace como true, o que faz com que o espaço atual seja a seleção padrão no menu:

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

Preencher itens de uma fonte de dados externa

Os menus de múltipla seleção também podem preencher itens de uma fonte de dados externa ou de terceiros. Para usar uma fonte de dados externa, especifique o campo externalDataSource no widget SelectionInput que contém a função que consulta e retorna itens da fonte de dados.

Para reduzir as solicitações a uma fonte de dados externa, é possível incluir itens sugeridos que aparecem no menu de múltipla seleção antes que os usuários digitem no menu. Por exemplo, você pode preencher os contatos pesquisados recentemente para o usuário. Para preencher itens sugeridos de uma fonte de dados externa, especifique objetos SelectionItem estáticos.

O código abaixo mostra um menu de múltipla seleção que consulta e preenche itens de uma fonte de dados externa:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "externalDataSource": { "function": "FUNCTION" },
    // Suggested items loaded by default.
    // The list is static here but it could be dynamic.
    "items": [FUNCTION]
  }
}

Substitua FUNCTION pelo URL HTTP ou pelo nome da função do Apps Script que consulta o banco de dados externo. Para um exemplo completo que mostra como retornar itens sugeridos, consulte a seção Sugerir itens de seleção múltipla.

Receber dados de widgets interativos

Sempre que os usuários clicam em um botão, a ação dos apps de chat é acionada com informações sobre a interação. No commonEventObject do payload do evento, o objeto formInputs contém todos os valores que o usuário insere.

É possível recuperar os valores do objeto commonEventObject.formInputs.WIDGET_NAME, em que WIDGET_NAME é o campo name especificado para o widget. Os valores são retornados como um tipo de dados específico para o widget.

A seguir, mostramos uma parte de um objeto de evento em que um usuário inseriu valores para cada widget:

{
  "commonEventObject": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

Para receber os dados, o app do Chat processa o objeto de evento para receber os valores que os usuários inserem nos widgets. A tabela a seguir mostra como receber o valor de um widget de entrada de formulário. Para cada widget, a tabela mostra o tipo de dados aceito pelo widget, onde o valor é armazenado no objeto de evento e um valor de exemplo.

Depois que o app de chat recebe dados, ele pode fazer o seguinte:

• Para cards que contêm um menu de múltipla seleção, preencha ou sugira itens com base no que o usuário digita no menu.
• Transfira os dados para outro card para que o usuário possa revisar as informações ou continuar para a próxima seção do formulário.
• Responda ao usuário para confirmar que ele preencheu o formulário.

Sugerir itens de seleção múltipla

Se um card tiver um menu de múltipla seleção que preencha itens de uma fonte de dados externa, o app Chat poderá retornar itens sugeridos com base no que os usuários digitam no menu. Por exemplo, se um usuário começar a digitar Atl para um menu que preenche cidades nos Estados Unidos, o app de chat pode sugerir automaticamente Atlanta antes que o usuário termine de digitar. O app de chat pode sugerir até 100 itens.

Para sugerir e preencher dinamicamente itens em um menu de múltipla escolha, o widget SelectionInput no card precisa especificar uma função que consulta a fonte de dados externa. Para retornar itens sugeridos, a função precisa fazer o seguinte:

1. Processe um objeto de evento, que o app do Chat recebe quando os usuários digitam no menu.
2. No objeto do evento, extraia o valor digitado pelo usuário, que é representado no campo event.commonEventObject.parameters["autocomplete_widget_query"].
3. Consulte a origem de dados usando o valor de entrada do usuário para receber uma ou mais SelectionItems para sugerir ao usuário.
4. Retorne itens sugeridos retornando a ação RenderActions com um objeto modifyCard.

O exemplo de código abaixo mostra como um app de chat sugere dinamicamente itens no menu de seleção múltipla em um card. Quando um usuário digita no menu, a função ou o endpoint fornecido no campo externalDataSource do widget consulta uma fonte de dados externa e sugere itens que o usuário pode selecionar.

/**
 * Google Cloud Function that responds to events sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.selectionInput = function selectionInput(req, res) {
  if (req.method === 'GET' || !req.body.chat) {
    return res.send('Hello! This function is meant to be used ' +
        'in a Google Chat Space.');
  }
  // Stores the Google Chat event
  const chatEvent = req.body.chat;

  // Handle user interaction with multiselect.
  if(chatEvent.widgetUpdatedPayload) {
    return res.send(queryContacts(req.body));
  }
  // Replies with a card that contains the multiselect menu.
  return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "FUNCTION_URL" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}});
};

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a selection item in the menu.
 */
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

/**
* Responds to a Message trigger in Google Chat.
*
* @param {Object} event the event object from Google Chat
* @return {Object} Response from the Chat app.
*/
function onMessage(event) {
  // Replies with a card that contains the multiselect menu.
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "queryContacts" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact"3")]
        }
      }]}]}
    }]
  }}}}};
}

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the interactive event.
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
* Generate a suggested contact given an ID.
*
* @param {String} id The ID of the contact to return.
* @return {Object} The contact formatted as a selection item in the menu.
*/
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Transferir dados para outro cartão

Depois que um usuário envia informações de um cartão, talvez seja necessário retornar outros cartões para fazer o seguinte:

• Crie seções distintas para ajudar os usuários a preencher formulários mais longos.
• Permita que os usuários visualizem e confirmem as informações do cartão inicial para que eles possam revisar as respostas antes de enviar.
• Preencha dinamicamente as partes restantes do formulário. Por exemplo, para solicitar que os usuários criem um horário, um app de chat pode mostrar um card inicial que solicita o motivo do horário e, em seguida, preenche outro card que oferece horários disponíveis com base no tipo de horário.

Para transferir a entrada de dados do card inicial, crie o widget button com actionParameters que contém o name do widget e o valor que o usuário insere, conforme mostrado neste exemplo:

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "submitForm",
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

Em que WIDGET_NAME é o name do widget e o USER_INPUT_VALUE é o que o usuário insere. Por exemplo, para um campo de texto que coleta o nome de uma pessoa, o nome do widget é contactName, e um valor de exemplo é Kai O.

Quando um usuário clica no botão, o app Chat recebe um objeto de evento do qual você pode receber dados.

Responder a um envio de formulário

Depois de receber os dados de uma mensagem ou caixa de diálogo do cartão, o app de chat responde confirmando o recebimento ou retornando um erro.

No exemplo abaixo, um app de chat envia uma mensagem de texto para confirmar que recebeu um formulário enviado de uma mensagem de cartão.

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  const chatMessage = chatEvent.messagePayload.message;

  // Handle message payloads in the event object
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(chatMessage, chatEvent.user));
  // Handle button clicks on the card
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openDialog":
            return res.send(openDialog());
        case "openNextCard":
            return res.send(openNextCard(req.body));
        case "submitForm":
            return res.send(submitForm(req.body));
    }
  }
};

/**
 * Submits information from a dialog or card message.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

/**
 * Sends private text message that confirms submission.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

Para processar e fechar uma caixa de diálogo, retorne um objeto RenderActions que especifique se você quer enviar uma mensagem de confirmação, atualizar a mensagem ou o card original ou apenas fechar a caixa de diálogo. Para conferir as etapas, consulte Fechar uma caixa de diálogo.

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.