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.

Uma caixa de diálogo com vários widgets diferentes.
Figura 1: um exemplo de app do Chat que abre uma caixa de diálogo para coletar dados de contato.

Os apps de chat solicitam informações dos usuários para realizar ações dentro ou fora do Chat, incluindo as 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 do Chat a um ou mais espaços.
  • Criar ou atualizar informações em outros aplicativos do Google Workspace. Por exemplo, permitir 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 do 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

HTTP

Um app do Google Chat que recebe e responde a interações do usuário. Para criar um, conclua o guia de início rápido de HTTP.

Apps Script

Um app do Google Chat que recebe e responde a interações do usuário. Para criar um, conclua o guia de início rápido do Apps Script.

Criar formulários usando cards

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

  • Mensagens que contêm um ou mais cards.
  • Páginas iniciais, que são cards que aparecem na guia Início em mensagens diretas com o app do Chat.
  • Caixas de diálogo, que são cards abertos em uma nova janela de mensagens e páginas iniciais.

Os apps do Chat podem criar os cards usando os seguintes widgets:

  • Widgets de entrada de formulário que solicitam informações dos usuários. Se quiser, adicione validação aos widgets de entrada de formulário para garantir que os usuários insiram e formatem as informações corretamente. Os apps do Chat podem usar os seguintes widgets de entrada de formulário:

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

No exemplo a seguir, um card coleta dados de contato usando uma entrada de texto, um seletor de data e hora e uma entrada 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.

Adicionar um menu suspenso

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

É possível preencher itens para um menu suspenso usando as seguintes fontes de dados:

Preencher itens de uma fonte de dados do Google Workspace

Para preencher itens de fontes de dados do Google Workspace, como usuários do Google Workspace, especifique o campo platformDataSource em um objeto DataSourceConfig. Ao contrário de outros tipos de entrada de seleção, você omite objetos SelectionItem, porque esses itens de seleção são originados dinamicamente do Google Workspace.

O código a seguir mostra um menu suspenso de usuários do Google Workspace:

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "contacts",
            "type": "DROPDOWN",
            "label": "Select contact from organization",
            "dataSourceConfigs": [
              {
                "platformDataSource": {
                  "commonDataSource": "USER"
                },
                "minCharactersTrigger": 1
              }
            ]
          }
        }
      ]
    }
  ]
}

Preencher itens de uma fonte de dados externa

Os menus suspensos também podem preencher itens de uma fonte de dados externa ou de terceiros. Para usar uma fonte de dados externa, especifique o campo remoteDataSource em um objeto DataSourceConfig que contém a função que consulta e retorna itens da fonte de dados.

Para reduzir as solicitações para uma fonte de dados externa, inclua itens sugeridos que aparecem no menu suspenso antes que os usuários digitem no menu. Para preencher itens sugeridos de uma fonte de dados externa, especifique objetos SelectionItem estáticos.

O código a seguir mostra um menu suspenso que consulta e preenche itens de uma fonte de dados externa:

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "crm_leads",
            "type": "DROPDOWN",
            "label": "Select CRM Lead",
            "dataSourceConfigs": [
              {
                "remoteDataSource": {
                  "function": "getCrmLeads"
                },
                "minCharactersTrigger": 2
              }
            ],
            "items": [
              {
                "text": "Suggested Lead 1",
                "value": "lead-1"
              }
            ]
          }
        }
      ]
    }
  ]
}

Para ver um exemplo completo que mostra como retornar itens sugeridos, consulte a seção Sugerir itens de seleção.

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 do 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 em uma lista de contatos:

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

  • Dados do Google Workspace, que incluem usuários ou espaços do Chat de 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, você pode usar menus de seleção múltipla para ajudar um usuário a selecionar em 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 fontes 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 originados dinamicamente do Google Workspace.

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

JSON

{
  "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 do Chat. Para preencher os 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 torna o espaço atual a seleção padrão no menu:

JSON

{
  "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 seleção múltipla 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 para uma fonte de dados externa, inclua itens sugeridos que aparecem no menu de seleção múltipla antes que os usuários digitem no menu. Por exemplo, é possível 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 exemplo de código a seguir mostra um menu de seleção múltipla que consulta e preenche itens de uma fonte de dados externa:

Node.js

node/chat/selection-input/index.js
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")]
}

Substitua FUNCTION_URL pelo endpoint HTTP que consulta a fonte de dados externa.

Python

python/chat/selection-input/main.py
'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': [get_suggested_contact("3")]
}

Substitua FUNCTION_URL pelo endpoint HTTP que consulta a fonte de dados externa.

Java

java/chat/selection-input/src/main/java/com/google/chat/selectionInput/App.java
.setSelectionInput(new GoogleAppsCardV1SelectionInput()
  .setName("contacts")
  .setType("MULTI_SELECT")
  .setLabel("Selected contacts")
  .setMultiSelectMaxSelectedItems(3)
  .setMultiSelectMinQueryLength(1)
  .setExternalDataSource(new GoogleAppsCardV1Action().setFunction(FUNCTION_URL))
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  .setItems(List.of(getSuggestedContact("3")))))))))));

Substitua FUNCTION_URL pelo endpoint HTTP que consulta a fonte de dados externa.

Apps Script

Este exemplo envia uma mensagem de card retornando o JSON do card. Também é possível usar o serviço de cards do Apps Script.

apps-script/chat/selection-input/selection-input.gs
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")]
}

Para ver um exemplo completo que mostra como retornar itens sugeridos, consulte a seção Sugerir itens de seleção.

Receber dados de widgets interativos

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

É possível recuperar os valores do objeto event.commonEventObject.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.

Veja a seguir 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 determinado 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 objeto de evento e um exemplo de valor.

Widget de entrada de formulário Tipo de dados de entrada Valor de entrada do objeto de evento Valor de exemplo
textInput stringInputs event.commonEventObject.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs Para receber o primeiro ou único valor, event.commonEventObject.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker que aceita apenas datas. dateInput event.commonEventObject.formInputs.contactBirthdate.dateInput.msSinceEpoch. 1000425600000

Depois que o app do Chat recebe os dados, ele pode fazer o seguinte:

  • Para cards que contêm um menu de seleção múltipla, 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

Se um card tiver um menu de seleção múltipla ou um menu suspenso que preenche itens de uma fonte de dados externa, o app do 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 em um menu que preenche cidades nos Estados Unidos, seu app do Chat poderá sugerir automaticamente Atlanta antes que o usuário termine de digitar. O app do Chat pode sugerir até 100 itens.

Para sugerir e preencher dinamicamente itens em uma entrada de seleção, o widget SelectionInput no card precisa especificar uma função que consulte a fonte de dados externa. Para menus de seleção múltipla, especifique o campo externalDataSource. Para menus suspensos, especifique o campo remoteDataSource em um objeto DataSourceConfig.

Também é possível configurar o número de caracteres que um usuário digita antes que o menu retorne sugestões. Para menus de seleção múltipla, defina o campo multiSelectMinQueryLength. Para menus suspensos, defina o campo min_characters_trigger no DataSourceConfig.

Para retornar itens sugeridos, a função precisa fazer o seguinte:

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

O exemplo de código a seguir mostra como um app do Chat sugere itens dinamicamente 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.

Node.js

node/chat/selection-input/index.js
/**
 * Web app 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
 */
app.post('/', async (req, res) => {
  // Stores the Google Chat event
  const chatEvent = req.body.chat;

  // Handle user interaction with multiselect.
  if(chatEvent.widgetUpdatedPayload) {
    return res.json(queryContacts(req.body));
  }

  // Replies with a card that contains the multiselect menu.
  return res.json({ 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
  };
}

Substitua FUNCTION_URL pelo endpoint HTTP que consulta a fonte de dados externa.

Python

python/chat/selection-input/main.py
@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: The response
  """
  # Stores the Google Chat event
  chatEvent = request.get_json().get('chat')

  # Handle user interaction with multiselect.
  if chatEvent.get('widgetUpdatedPayload') is not None:
    return json.jsonify(query_contacts(request.get_json()))

  # Replies with a card that contains the multiselect menu.
  return json.jsonify({ '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': [get_suggested_contact("3")]
        }
      }]}]}
    }]}
  }}}})


def query_contacts(event: dict) -> dict:
  """Get contact suggestions based on text typed by users.

  Args:
      event (Mapping[str, Any]): The event object that contains the user's query

  Returns:
      Mapping[str, Any]: The response with contact suggestions.
  """
  query = event.get("commonEventObject").get("parameters").get("autocomplete_widget_query")
  return { 'action': { 'modifyOperations': [{ 'updateWidget': { 'selectionInputWidgetSuggestions': { 'suggestions': list(
    filter(lambda e: query is None or query in e["text"], [
      # The list is static here but it could be dynamic.
      get_suggested_contact("1"), get_suggested_contact("2"), get_suggested_contact("3"), get_suggested_contact("4"), get_suggested_contact("5")
    # Only return items based on the query from the user
    ])
  )}}}]}}


def get_suggested_contact(id: str) -> dict:
  """Generate a suggested contact given an ID.

  Args:
      id (str): The ID of the contact to return.

  Returns:
      Mapping[str, Any]: The contact formatted as a selection item in the menu.
  """
  return {
    'value': id,
    'startIconUri': "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    'text': "Contact " + id
  }

Substitua FUNCTION_URL pelo endpoint HTTP que consulta a fonte de dados externa.

Java

java/chat/selection-input/src/main/java/com/google/chat/selectionInput/App.java
@SpringBootApplication
@RestController
// Web app that responds to events sent from a Google Chat space.
public class App {
  private static final String FUNCTION_URL = "your-function-url";

  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /**
   * Handle requests from Google Chat
   * 
   * @param event the event object sent by Google Chat
   * @return The response to be sent back to Google Chat
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    // Stores the Google Chat event
    JsonNode chatEvent = event.at("/chat");

    // Handle user interaction with multiselect.
    if (!chatEvent.at("/widgetUpdatedPayload").isEmpty()) {
      return queryContacts(event);
    }

    // Replies with a card that contains the multiselect menu.
    Message message = new Message().setCardsV2(List.of(new CardWithId()
      .setCardId("contactSelector")
      .setCard(new GoogleAppsCardV1Card()
        .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(new GoogleAppsCardV1Widget()
          .setSelectionInput(new GoogleAppsCardV1SelectionInput()
            .setName("contacts")
            .setType("MULTI_SELECT")
            .setLabel("Selected contacts")
            .setMultiSelectMaxSelectedItems(3)
            .setMultiSelectMinQueryLength(1)
            .setExternalDataSource(new GoogleAppsCardV1Action().setFunction(FUNCTION_URL))
            // Suggested items loaded by default.
            // The list is static here but it could be dynamic.
            .setItems(List.of(getSuggestedContact("3")))))))))));

    return new GenericJson() {{
      put("hostAppDataAction", new GenericJson() {{
        put("chatDataAction", new GenericJson() {{
          put("createMessageAction", new GenericJson() {{
            put("message", message);
          }});
        }});
      }});
    }};
  }

  /**
   * Get contact suggestions based on text typed by users.
   *
   * @param event the event object that contains the user's query.
   * @return The response with contact suggestions.
   */
  GenericJson queryContacts(JsonNode event) throws Exception {
    String query = event.at("/commonEventObject/parameters/autocomplete_widget_query").asText();
    List<GoogleAppsCardV1SelectionItem> suggestions = List.of(
      // 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
    ).stream().filter(e -> query == null || e.getText().indexOf(query) > -1).toList();

    return new GenericJson() {{
      put("action", new GenericJson() {{
        put("modifyOperations", List.of(new GenericJson() {{
          put("updateWidget", new GenericJson() {{
            put("selectionInputWidgetSuggestions", new GenericJson() {{
              put("suggestions", suggestions);
            }});
          }});
        }}));
      }});
    }};
  }

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

Substitua FUNCTION_URL pelo endpoint HTTP que consulta a fonte de dados externa.

Apps Script

Este exemplo envia uma mensagem de card retornando o JSON do card. Também é possível usar o serviço de cards do Apps Script.

apps-script/chat/selection-input/selection-input.gs
/**
* 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 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
  };
}

Transferir dados para outro cartão

Depois que um usuário envia informações de um card, talvez seja necessário retornar outros cards para realizar uma das seguintes ações:

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

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

Node.js

node/chat/contact-form-app/index.js
{ buttonList: { buttons: [{
  text: "SUBMIT",
  onClick: { action: {
    function: FUNCTION_URL,
    parameters: [
      { key: "actionName", value: "submitDialog" },
      // Pass input values as parameters for last dialog step (submission)
      { key: "contactName", value: name },
      { key: "contactBirthdate", value: birthdate },
      { key: "contactType", value: type }
    ]
  }}
}]}}

Substitua FUNCTION_URL pelo endpoint HTTP que processa os cliques no botão.

Python

python/chat/contact-form-app/main.py
{ 'buttonList': { 'buttons': [{
  'text': "SUBMIT",
  'onClick': { 'action': {
    'function': FUNCTION_URL,
    'parameters': [
      { 'key': "actionName", 'value': "submitDialog" },
      # Pass input values as parameters for last dialog step (submission)
      { 'key': "contactName", 'value': name },
      { 'key': "contactBirthdate", 'value': birthdate },
      { 'key': "contactType", 'value': type }
    ]
  }}
}]}}

Substitua FUNCTION_URL pelo endpoint HTTP que processa os cliques no botão.

Java

java/chat/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(FUNCTION_URL)
      .setParameters(List.of(
        new GoogleAppsCardV1ActionParameter().setKey("actionName").setValue("submitDialog"),
        // Pass input values as parameters for last dialog step (submission)
        new GoogleAppsCardV1ActionParameter().setKey("contactName").setValue(name),
        new GoogleAppsCardV1ActionParameter().setKey("contactBirthdate").setValue(birthdate),
        new GoogleAppsCardV1ActionParameter().setKey("contactType").setValue(type))))))))))));

Substitua FUNCTION_URL pelo endpoint HTTP que processa os cliques no botão.

Apps Script

Este exemplo envia uma mensagem de card retornando o JSON do card. Também é possível usar o serviço de cards do Apps Script.

apps-script/chat/contact-form-app/Code.gs
{ buttonList: { buttons: [{
  text: "SUBMIT",
  onClick: { action: {
    function: "submitDialog",
    // Pass input values as parameters for last dialog step (submission)
    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 objeto de evento do qual você pode receber dados.

Responder a um envio de formulário

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

No exemplo a seguir, um app do Chat envia uma mensagem de texto para confirmar que recebeu um formulário enviado de uma mensagem de card.

Node.js

node/chat/contact-form-app/index.js
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
  text: "✅ " + event.commonEventObject.parameters["contactName"] + " has been added to your contacts."
}}}}};

Python

python/chat/contact-form-app/main.py
return { 'hostAppDataAction': { 'chatDataAction': { 'createMessageAction': { 'message': {
  'text': "✅ " + event.get('commonEventObject').get('parameters')["contactName"] + " has been added to your contacts."
}}}}}

Java

java/chat/contact-form-app/src/main/java/com/google/chat/contact/App.java
return new GenericJson() {{
  put("hostAppDataAction", new GenericJson() {{
    put("chatDataAction", new GenericJson() {{
      put("createMessageAction", new GenericJson() {{
        put("message", new Message()
          .setText( "✅ " + event.at("/commonEventObject/parameters/contactName").asText() +
                    " has been added to your contacts."));
      }});
    }});
  }});
}};

Apps Script

Este exemplo envia uma mensagem de card retornando o JSON do card. Também é possível usar o serviço de cards do Apps Script.

apps-script/chat/contact-form-app/Code.gs
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
  text: "✅ " + event.commonEventObject.parameters["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 ver as etapas, consulte Fechar uma caixa de diálogo.

Resolver problemas

Nesta seção, apresentamos as etapas de solução de problemas para códigos de erro específicos e comportamentos de execução ao interagir com caixas de diálogo no Chat.

As interações de caixa de diálogo retornam "Erro não especificado ao invocar o complemento"

Ao interagir com uma caixa de diálogo, se você encontrar registros de erro com a mensagem "Erro não especificado ao invocar o complemento" e o código 13, isso geralmente indica um erro interno ou que o endpoint HTTP do app do Chat não conseguiu processar a solicitação ou retornar uma resposta válida.

Para resolver esse erro:

  • Verifique se há exceções não tratadas ou falhas nos registros do endpoint HTTP.
  • Verifique se o endpoint responde às solicitações em até 30 segundos. Se o endpoint levar mais de 30 segundos para ser executado, o Chat não poderá processar a resposta, e a interação vai falhar. Para mais detalhes, consulte Limites de taxa e práticas recomendadas.
  • Verifique se o endpoint retorna uma resposta válida. Para envios de caixas de diálogo, o endpoint precisa retornar um objeto RenderActions no formato JSON correto. Se a resposta estiver incorreta ou não tiver os campos obrigatórios, a interação da caixa de diálogo poderá falhar.

Quando um app do Google Chat ou card retorna um erro, a interface do Chat mostra a mensagem "Algo deu errado". 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 do Chat ou card 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 você a corrigir erros quando o registro de erros para apps do Chat está ativado. Para receber ajuda para visualizar, depurar e corrigir erros, consulte Resolver problemas e corrigir erros do Google Chat.

Apps do Chat que não são complementos: ler dados de formulários inseridos pelos usuários em cards

A documentação a seguir se aplica a apps do Chat que não são complementos do Google Workspace. Para migrar um app do Chat que não é um complemento, consulte Converter um app do Google Chat em um complemento do Google Workspace.

Criar formulários usando cards

Para ver um exemplo de um app do Chat que não é um complemento e usa um formulário de contato com uma entrada de texto, um seletor de data e hora e uma entrada de seleção, consulte o seguinte código:

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
        }
      ]
    }
  }
];

Receber dados de widgets interativos

Sempre que os usuários clicam em um botão, os apps do Chat que não são complementos recebem um evento de interação que depende do local do botão:

  • Se o botão estiver em uma mensagem ou caixa de diálogo, os apps do Chat que não são complementos vão receber um evento de interação CARD_CLICKED com informações sobre a interação. O payload dos eventos de interação CARD_CLICKED contém um objeto common.formInputs (event.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).

    Veja a seguir 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"]
    }}}
  }}
}

  • Se o botão estiver em uma página inicial, os apps do Chat que não são complementos vão receber um evento de interação SUBMIT_FORM. O payload do evento de interação contém um objeto commonEventObject.formInputs (event.commonEventObject.formInputs) com todos os valores inseridos pelo usuário.

    É possível recuperar os valores do objeto commonEventObject.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).

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

    HTTP

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

    Apps Script 

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

Para receber os dados, um app do Chat que não é um complemento 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 determinado widget de entrada de formulário. Para cada widget, a tabela mostra o tipo de dados que ele aceita, onde o valor é armazenado no evento de interação e um exemplo de valor.

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 receber o primeiro ou único valor, event.common.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker que aceita apenas datas. dateInput event.common.formInputs.contactBirthdate.dateInput.msSinceEpoch. 1000425600000

Transferir dados para outro cartão

Para transferir a entrada de dados do card inicial em um app do Chat que não é um complemento, crie o widget button com actionParameters que contenham o name do widget e o valor inserido pelo usuário, conforme mostrado no exemplo a seguir:

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 que não é um complemento recebe um evento de interação CARD_CLICKED do qual você pode receber dados.

Responder a um envio de formulário

No exemplo a seguir, um app do Chat que não é um complemento envia uma mensagem de texto para confirmar que recebeu um formulário enviado de uma mensagem de caixa de diálogo ou de card:

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.
const errorMessage = "Don't forget to name your new contact!";
if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { actionStatus: {
      statusCode: "INVALID_ARGUMENT",
      userFacingMessage: 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.
error_message = "Don't forget to name your new contact!"
if contact_name == "" and "SUBMIT_DIALOG" == event.get('dialogEventType'):
  return { 'actionResponse': {
    'type': "DIALOG",
    'dialogAction': { 'actionStatus': {
      'statusCode': "INVALID_ARGUMENT",
      'userFacingMessage': 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.
String errorMessage = "Don't forget to name your new contact!";
if (contactName.isEmpty() && 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))));
}

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.
const errorMessage = "Don't forget to name your new contact!";
if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { actionStatus: {
      statusCode: "INVALID_ARGUMENT",
      userFacingMessage: errorMessage
    }}
  }};
}

Para processar e fechar uma caixa de diálogo em um app do Chat que não seja um complemento, 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 ver as etapas, consulte Fechar uma caixa de diálogo.