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.

Os apps de chat solicitam informações dos usuários para realizar ações fora do Chat, inclusive das seguintes maneiras:

• 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.
• Criar ou atualizar informações em outros aplicativos do Google Workspace. Para permitir que os usuários criem um evento do Google Agenda.
• Permita que os usuários acessem e atualizem recursos em outros apps ou serviços da Web. Para exemplo, um app do Chat pode ajudar os usuários a atualizar status de um tíquete de suporte diretamente em um espaço do Chat.

Pré-requisitos

• Serviço HTTP com o Google Cloud Functions
• Google Apps Script
• Google Cloud Dialogflow CX
• Google Cloud Pub/Sub

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 de chat podem usar as seguintes interfaces:

• Mensagens que contêm um ou mais cards.
• Páginas iniciais, que é um card que aparece na guia Início em mensagens diretas com o app Chat.
• Caixas de diálogo, que são cards que abrem 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ários que solicitam informações dos usuários. Também é possível adicionar validação para formar widgets de entrada, para garantir que os usuários insiram e formatem informações corretamente. Os apps de chat podem usar os seguintes widgets de entrada de formulário:

  • Entradas de texto (textInput) para texto de formato livre ou sugerido.
  • 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 itens de fontes de dados estáticas ou dinâmicas. Por exemplo, os usuários podem selecionar em uma lista de espaços do Chat de que participa.
  • 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 clicar no botão, o app do Chat poderá processar as informações que recebe.

Veja a seguir um card que consiste em três tipos diferentes de data e entradas de horário:

Para conferir mais exemplos de widgets interativos que podem ser usados para coletar informações, consulte Projetar um card ou diálogo interativo.

Receber dados de widgets interativos

Sempre que os usuários clicam em um botão, os apps de chat recebem um evento de interação CARD_CLICKED que contém informações sobre a interação. O payload dos eventos de interação CARD_CLICKED contém um objeto common.formInputs com todos os valores inseridos pelo usuário.

É possível recuperar os valores do objeto common.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 (representado como um objeto Inputs). No exemplo abaixo, um card coleta informações de contato usando um campo de texto, um seletor de data e hora e um widget de seleção:

{
  "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
      }
    ]
  }
}

Processar o evento de interação

Quando um usuário insere dados em um card ou caixa de diálogo, o app do Chat recebe um evento de interação CARD_CLICKED que contém os valores inseridos pelo usuário.

Veja a seguir uma parte de um evento de interação CARD_CLICKED em que que o usuário inseriu valores para cada widget:

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

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

Para receber os dados, o app do Chat processa as seguintes informações: 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 evento de interação e um valor de exemplo.

Transferir dados para outro cartão

Depois que um usuário envia informações de um cartão, pode ser necessário retornar cards adicionais para realizar uma das seguintes ações:

• 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.
• Preencher dinamicamente as partes restantes do formulário. Por exemplo, para solicitar para que os usuários marquem um horário, um app do Chat pode exibe um card inicial que solicita o motivo do agendamento e Depois, ele preenche outro card que mostra os horários disponíveis com base no tipo de agendamento.

Para transferir a entrada de dados do card inicial, crie o button widget com actionParameters que contêm o name do widget e o valor inserido pelo usuário, conforme mostrado no exemplo a seguir:

{
  "buttonList": {
    "buttons": [{
      "text": "Submit",
      "onClick": {
        "action": {
          "function": "openNextCard",
          "parameters": [{
            "key": "WIDGET_NAME",
            "value": "USER_INPUT_VALUE"
          }]
        }
      }
    }]
  }
}

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

Quando um usuário clica no botão, o app de chat recebe um evento de interação CARD_CLICKED. Para recuperar os valores, você pode usar o método event.common.parameters objeto.

Confira a seguir um exemplo de como transmitir parâmetros que contêm instruções inserir dados para uma função que abre o próximo cartão:

// Respond to button clicks on cards or dialogs
if (event.type === "CARD_CLICKED") {

  // Open another card.
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    openNextCard(event);
  }
}

  # Respond to button clicks on cards or dialogs
  if request.get('type') == 'CARD_CLICKED':
    if invoked_function := request.get('common', dict()).get('invokedFunction'):
      if invoked_function == 'open_next_card':
        parameters = request.get('common', dict()).get('parameters'),
        return open_next_card(parameters)

// Respond to button clicks on cards or dialogs
function onCardClick(event) {
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    return openNextCard(parameters);
  }
}

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.

function submitCardForm(contactName, contactBirthdate, contactType) {
    return {
      "text": "You entered the following contact information:\n\n" +
      "*Name:* " + contactName + "\n" +
      "*Birthdate:* " + contactBirthdate + "\n" +
      "*Type:* " + contactType
      }
}

Para processar e fechar uma caixa de diálogo, retorne um objeto ActionResponse 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 exibe nenhuma mensagem de erro, mas o app do Chat ou produz um resultado inesperado; por exemplo, uma mensagem de cartão 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 receber ajuda com a visualização, depurar e corrigir erros, consulte Resolver problemas e corrigir erros do Google Chat.

Temas relacionados

• Confira o exemplo do Gerenciador de contatos, que é um app do Chat que solicita que os usuários preencham um formulário de contato em mensagens de card e caixas de diálogo.
• Abrir caixas de diálogo interativas