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

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

Uma caixa de diálogo com vários widgets diferentes.
Figura 1: um exemplo de app de chat que abre uma caixa de diálogo para coletar informações de contato.

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 definam e adicionem o app do Chat a um ou mais espaços.
  • Criar ou atualizar 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

Node.js

Um app do Google Chat com recursos interativos ativados. Para criar um app de chat interativo usando um serviço HTTP, conclua este guia de início rápido.

Python

Um app do Google Chat que tenha recursos interativos ativados. Para criar um app do Chat interativo usando um serviço HTTP, conclua este guia de início rápido.

Java

Um app do Google Chat que tenha recursos interativos ativados. Para criar um app do Chat interativo usando um serviço HTTP, conclua este guia de início rápido.

Apps Script

Um app do Google Chat que tenha recursos interativos ativados. Para criar um app do Chat interativo no Apps Script, conclua este guia de início rápido.

Criar formulários usando cards

Para coletar informações, os apps de chat criam formulários e as entradas deles e os transformam 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 são abertos em uma nova janela a partir 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. Também é possível adicionar validação para formar widgets de entrada e 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 sugerido ou em formato livre.
    • Entradas de seleção (selectionInput) são elementos selecionáveis da interface, 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 uma lista de espaços do Chat em que são participantes.
    • 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 recebidas.

No exemplo abaixo, um card coleta dados de contato usando uma entrada de texto, um seletor de data e hora e um widget de entrada de seleção:

Node.js

node/contact-form-app/index.js
/**
 * 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
        }
      ]
    }
  }
];

Python

python/contact-form-app/main.py
# 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
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
        }
      ]
    }
  }
]

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
// 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
final static private List<GoogleAppsCardV1Widget> CONTACT_FORM_WIDGETS = List.of(
  new GoogleAppsCardV1Widget().setTextInput(new GoogleAppsCardV1TextInput()
    .setName("contactName")
    .setLabel("First and last name")
    .setType("SINGLE_LINE")),
  new GoogleAppsCardV1Widget().setDateTimePicker(new GoogleAppsCardV1DateTimePicker()
    .setName("contactBirthdate")
    .setLabel("Birthdate")
    .setType("DATE_ONLY")),
  new GoogleAppsCardV1Widget().setSelectionInput(new GoogleAppsCardV1SelectionInput()
    .setName("contactType")
    .setLabel("Contact type")
    .setType("RADIO_BUTTON")
    .setItems(List.of(
      new GoogleAppsCardV1SelectionItem()
        .setText("Work")
        .setValue("Work")
        .setSelected(false),
      new GoogleAppsCardV1SelectionItem()
        .setText("Personal")
        .setValue("Personal")
        .setSelected(false)))));

Apps Script

apps-script/contact-form-app/contactForm.gs
/**
 * 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
        }
      ]
    }
  }
];

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 do Chat recebem um evento de interação CARD_CLICKED com informações sobre a interação. O payload de 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 que você especificou para o widget. Os valores são retornados como um tipo de dados específico para o widget (representado como um objeto Inputs).

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

HTTP

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

Apps Script 

{
  "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 o evento de interação 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 que o widget aceita, onde o valor é armazenado no evento de interação e um valor de exemplo.

Widget de entrada de formulário Tipo de dados de entrada Valor de entrada do evento de interação Valor de exemplo
textInput stringInputs event.common.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs Para acessar o primeiro ou único valor, event.common.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker que só aceita datas. dateInput event.common.formInputs.contactBirthdate.dateInput.msSinceEpoch. 1000425600000

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:

  • Ajude os usuários a preencher formulários mais longos criando seções distintas.
  • 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 mostra os 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 contenha o name do widget e o valor que o usuário insere, conforme mostrado neste exemplo:

Node.js

node/contact-form-app/index.js
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Python

python/contact-form-app/main.py
'buttonList': { 'buttons': [{
  'text': "Submit",
  'onClick': { 'action': {
    'function': "submitForm",
    'parameters': [{
      'key': "contactName", 'value': name }, {
      'key': "contactBirthdate", 'value': birthdate }, {
      'key': "contactType", 'value': type
    }]
  }}
}]}

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
new GoogleAppsCardV1Widget().setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
  .setText("Submit")
  .setOnClick(new GoogleAppsCardV1OnClick().setAction(new GoogleAppsCardV1Action()
    .setFunction("submitForm")
    .setParameters(List.of(
      new GoogleAppsCardV1ActionParameter().setKey("contactName").setValue(name),
      new GoogleAppsCardV1ActionParameter().setKey("contactBirthdate").setValue(birthdate),
      new GoogleAppsCardV1ActionParameter().setKey("contactType").setValue(type))))))))));

Apps Script

apps-script/contact-form-app/main.gs
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

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

Responder ao envio de um formulário

Depois de receber os dados de uma mensagem ou caixa de diálogo do cartão, o app do Chat confirma o recebimento ou retorna um erro.

No exemplo a seguir, um app de chat envia uma mensagem de texto para confirmar que recebeu um formulário enviado de uma mensagem de diálogo ou de cartão.

Node.js

node/contact-form-app/index.js
const contactName = event.common.parameters["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 (event.dialogEventType === "SUBMIT_DIALOG") {
    return { actionResponse: {
      type: "DIALOG",
      dialogAction: { actionStatus: {
        statusCode: "INVALID_ARGUMENT",
        userFacingMessage: errorMessage
      }}
    }};
  } else {
    return {
      privateMessageViewer: event.user,
      text: errorMessage
    };
  }
}

Python

python/contact-form-app/main.py
contact_name = event.get('common').get('parameters')["contactName"]
# Checks to make sure the user entered a contact name.
# If no name value detected, returns an error message.
if contact_name == "":
  error_message = "Don't forget to name your new contact!"
  if "SUBMIT_DIALOG" == event.get('dialogEventType'):
    return { 'actionResponse': {
      'type': "DIALOG",
      'dialogAction': { 'actionStatus': {
        'statusCode': "INVALID_ARGUMENT",
        'userFacingMessage': error_message
      }}
    }}
  else:
    return {
      'privateMessageViewer': event.get('user'),
      'text': error_message
    }

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
String contactName = event.at("/common/parameters/contactName").asText();
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
if (contactName.isEmpty()) {
  String errorMessage = "Don't forget to name your new contact!";
  if (event.at("/dialogEventType") != null && "SUBMIT_DIALOG".equals(event.at("/dialogEventType").asText())) {
    return new Message().setActionResponse(new ActionResponse()
      .setType("DIALOG")
      .setDialogAction(new DialogAction().setActionStatus(new ActionStatus()
        .setStatusCode("INVALID_ARGUMENT")
        .setUserFacingMessage(errorMessage))));
  } else {
    return new Message()
      .setPrivateMessageViewer(new User().setName(event.at("/user/name").asText()))
      .setText(errorMessage);
  }
}

Apps Script

apps-script/contact-form-app/main.gs
const contactName = event.common.parameters["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 (event.dialogEventType === "SUBMIT_DIALOG") {
    return { actionResponse: {
      type: "DIALOG",
      dialogAction: { actionStatus: {
        statusCode: "INVALID_ARGUMENT",
        userFacingMessage: errorMessage
      }}
    }};
  } else {
    return {
      privateMessageViewer: event.user,
      text: errorMessage
    };
  }
}

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 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 ser exibida na interface do Chat, mensagens de erro descritivas e dados de registro estão disponíveis para ajudar você a corrigir erros quando a geração de registros de erros para apps do Chat está ativada. Se precisar de ajuda para visualizar, depurar e corrigir erros, consulte Resolver problemas e corrigir erros do Google Chat.