Adicionar elementos de interface interativos a cards

Nesta página, explicamos como adicionar widgets e elementos da interface aos cards para que os usuários possam interagir com seu app do Google Chat, por exemplo, clicando em um botão ou enviando informações.

Os apps do Chat podem usar as seguintes interfaces do Chat para criar cards interativos:

  • 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.

Quando os usuários interagem com os cards, os apps do Chat podem usar os dados recebidos para processar e responder de acordo. Veja mais detalhes em Coletar e processar informações de usuários do Google Chat.

Use o Card Builder para criar e visualizar mensagens e interfaces do usuário para apps do Chat:

Abra o Criador de Cards

Pré-requisitos

Um app do Google Chat configurado para receber e responder a interações do usuário. Para criar um app do Google Chat interativo, conclua um dos seguintes guias de início rápido com base na arquitetura do app que você quer usar:

Adicionar um botão

O widget ButtonList mostra um conjunto de botões. Os botões podem exibir texto, um ícone ou ambos. Cada Button oferece suporte a uma ação OnClick que ocorre quando os usuários clicam no botão. Exemplo:

  • Abra um hiperlink com OpenLink para fornecer mais informações aos usuários.
  • Executar um action que executa uma função personalizada, como chamar uma API.

Para acessibilidade, os botões são compatíveis com texto alternativo.

Adicionar um botão que executa uma função personalizada

Veja a seguir um card que consiste em um widget ButtonList com dois botões. Um botão abre a documentação para desenvolvedores do Google Chat em uma nova guia. O outro botão executa uma função personalizada chamada goToView() e transmite o parâmetro viewType="BIRD EYE VIEW".

Adicionar um botão com o estilo do Material Design

O exemplo a seguir mostra um conjunto de botões em diferentes estilos do Material Design.

Para aplicar o estilo do Material Design, não inclua o atributo "color".

Adicionar um botão com cor personalizada e um botão desativado

Para impedir que os usuários cliquem em um botão, defina "disabled": "true".

O exemplo a seguir mostra um card que consiste em um widget ButtonList com dois botões. Um botão usa o campo Color para personalizar a cor de fundo do botão. O outro botão é desativado com o campo Disabled, o que impede que o usuário clique no botão e execute a função.

Adicionar um botão com um ícone

O exemplo a seguir mostra um card que consiste em um widget ButtonList com dois widgets de ícone Button. Um botão usa o campo knownIcon para mostrar o ícone de e-mail integrado do Google Chat. O outro botão usa o campo iconUrl para mostrar um widget de ícone personalizado.

Adicionar um botão com um ícone e texto

O exemplo a seguir mostra um card com um widget ButtonList que solicita que o usuário envie um e-mail. O primeiro botão mostra um ícone de e-mail, e o segundo mostra um texto. O usuário pode clicar no ícone ou no botão de texto para executar a função sendEmail.

Personalizar o botão de uma seção recolhível

Personalize o botão de controle que fecha e abre seções em um card. É possível escolher entre diversos ícones ou imagens para representar visualmente o conteúdo da seção, facilitando a compreensão e a interação dos usuários com as informações.

Adicionar um menu flutuante

O Overflow menu pode ser usado em cards do Chat para oferecer mais opções e ações. Ele permite incluir mais opções sem sobrecarregar a interface do card, garantindo um design limpo e organizado.

Adicionar uma lista de ícones

O widget ChipList é uma maneira versátil e visualmente atraente de mostrar informações. Use listas de ícones para representar tags, categorias ou outros dados relevantes, facilitando a navegação e a interação dos usuários com seu conteúdo.

Coletar informações dos usuários

Nesta seção, explicamos como adicionar widgets que coletam informações, como texto ou seleções.

Para saber como processar o que os usuários inserem, consulte Coletar e processar informações de usuários do Google Chat.

Coletar texto

O widget TextInput oferece um campo em que os usuários podem inserir texto. O widget oferece sugestões que ajudam os usuários a inserir dados uniformes e ações de mudança, que são Actions executadas quando ocorre uma mudança no campo de entrada de texto, como um usuário adicionando ou excluindo texto.

Quando você precisar coletar dados abstratos ou desconhecidos dos usuários, use este widget TextInput. Para coletar dados definidos dos usuários, use o widget SelectionInput.

Veja a seguir um card que consiste em um widget TextInput:

Coletar datas ou horários

O widget DateTimePicker permite que os usuários insiram uma data, um horário ou ambos. Ou os usuários podem usar o seletor para escolher datas e horários. Se os usuários inserirem uma data ou hora inválida, o seletor vai mostrar um erro que solicita que os usuários insiram as informações corretamente.

Veja a seguir um card com três tipos diferentes de widgets DateTimePicker:

Permitir que os usuários selecionem itens

O widget SelectionInput oferece um conjunto de itens selecionáveis, como caixas de seleção, botões de opção, interruptores ou um menu suspenso. Você pode usar esse widget para coletar dados definidos e padronizados dos usuários. Para coletar dados indefinidos dos usuários, use o widget TextInput.

O widget SelectionInput aceita sugestões, que ajudam os usuários a inserir dados uniformes, e ações de mudança, que são Actions executadas quando ocorre uma mudança em um campo de entrada de seleção, como um usuário marcando ou desmarcando um item.

Os apps do Chat podem receber e processar o valor dos itens selecionados. Para saber mais sobre como trabalhar com entradas de formulário, consulte Processar informações inseridas pelos usuários.

Nesta seção, mostramos exemplos de cards que usam o widget SelectionInput. Os exemplos usam diferentes tipos de entradas de seção:

Adicionar uma caixa de seleção

O exemplo a seguir mostra um card que pede ao usuário para especificar se um contato é profissional, pessoal ou ambos, com um widget SelectionInput que usa caixas de seleção:

Adicionar um botão de opção

O exemplo a seguir mostra um card que pede ao usuário para especificar se um contato é profissional ou pessoal com um widget SelectionInput que usa botões de opção:

Adicionar uma chave

O exemplo a seguir mostra um card que pede ao usuário para especificar se um contato é profissional, pessoal ou ambos com um widget SelectionInput que usa chaves:

O exemplo a seguir mostra um card que pede ao usuário para especificar se um contato é profissional ou pessoal com um widget SelectionInput que usa um menu suspenso:

Preencher menus suspensos de forma dinâmica

Disponível para apps do Google Chat.

É possível preencher dinamicamente os itens de um menu suspenso com fontes de dados do Google Workspace ou de uma fonte de dados externa. Para usar fontes de dados dinâmicas, especifique o campo dataSourceConfigs, que é uma matriz de objetos DataSourceConfig. Cada DataSourceConfig pode conter um platformDataSource ou um remoteDataSource. No momento, apenas um DataSourceConfig é aceito.

Preencher itens 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 DataSourceConfig. Ao contrário do uso de items estático, 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 que preenche os 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

Para preencher itens de uma fonte de dados externa ou de terceiros, como um sistema de gestão de relacionamento com o cliente (CRM), use o campo remoteDataSource em um DataSourceConfig para especificar uma função que retorna itens da fonte de dados.

O código a seguir mostra um menu suspenso que preenche itens de um conjunto externo de contatos executando a função getCrmLeads:

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 reduzir as solicitações para uma fonte de dados dinâmica, inclua itens sugeridos que aparecem no menu suspenso antes que os usuários digitem. Também é possível configurar o menu suspenso para preencher automaticamente os itens com base no que os usuários digitam, definindo minCharactersTrigger no DataSourceConfig. Quando um usuário digita pelo menos o número de caracteres especificado em minCharactersTrigger, a função especificada em remoteDataSource é acionada. O objeto de evento transmitido à função inclui a entrada do usuário na chave autocomplete_widget_query.

Adicionar um menu de seleção múltipla

O exemplo a seguir mostra um card que pede ao usuário para selecionar contatos em um menu de seleção múltipla:

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

  • Usuários do Google Workspace: só é possível preencher usuários na mesma organização do Google Workspace.
  • Espaços do Chat: o usuário que insere itens no menu de seleção múltipla só pode ver e selecionar os espaços de que participa na organização do Google Workspace.

Para usar as fontes de dados do Google Workspace, especifique o campo platformDataSource. 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
          }
        }
      }
    }
  }
}

Os menus de seleção múltipla também podem preencher itens de uma fonte de dados externa ou de terceiros. 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).

Para usar uma fonte de dados externa, use o campo externalDataSource para especificar uma função que 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.

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

Preencher itens sugeridos de uma fonte de dados dinâmica

Para fontes de dados externas, também é possível preencher automaticamente e sugerir itens que os usuários começam a digitar em um menu de seleção múltipla ou menu suspenso. Por exemplo, se um usuário começar a digitar Atl em um menu que preenche cidades nos Estados Unidos, o app do Chat poderá sugerir automaticamente Atlanta antes que o usuário termine de digitar. Você pode sugerir até 100 itens.

Para retornar itens sugeridos, a função que consulta a fonte de dados externa 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
  };
}

Validar dados inseridos em cards

Nesta página, explicamos como validar os dados inseridos no action e nos widgets de um card. Por exemplo, é possível validar se um campo de entrada de texto tem texto inserido pelo usuário ou se contém um determinado número de caracteres.

Definir widgets obrigatórios para ações

Como parte do action do card, adicione nomes de widgets que uma ação precisa à lista requiredWidgets.

Se algum widget listado aqui não tiver um valor quando essa ação for invocada, o envio da ação do formulário será cancelado.

Quando "allWidgetsAreRequired": true é definido para uma ação, todos os widgets no card são exigidos por essa ação.

Definir uma ação allWidgetsAreRequired na seleção múltipla

JSON

{
  "sections": [
    {
      "header": "Select contacts",
      "widgets": [
        {
          "selectionInput": {
            "type": "MULTI_SELECT",
            "label": "Selected contacts",
            "name": "contacts",
            "multiSelectMaxSelectedItems": 3,
            "multiSelectMinQueryLength": 1,
            "onChangeAction": {
              "allWidgetsAreRequired": true
            },
            "items": [
              {
                "value": "contact-1",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 1",
                "bottomText": "Contact one description",
                "selected": false
              },
              {
                "value": "contact-2",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 2",
                "bottomText": "Contact two description",
                "selected": false
              },
              {
                "value": "contact-3",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 3",
                "bottomText": "Contact three description",
                "selected": false
              },
              {
                "value": "contact-4",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 4",
                "bottomText": "Contact four description",
                "selected": false
              },
              {
                "value": "contact-5",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 5",
                "bottomText": "Contact five description",
                "selected": false
              }
            ]
          }
        }
      ]
    }
  ]
}
Definir uma ação allWidgetsAreRequired em dateTimePicker

JSON

{
  "sections": [
    {
      "widgets": [
        {
          "textParagraph": {
            "text": "A datetime picker widget with both date and time:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_date_and_time",
            "label": "meeting",
            "type": "DATE_AND_TIME"
          }
        },
        {
          "textParagraph": {
            "text": "A datetime picker widget with just date:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_date_only",
            "label": "Choose a date",
            "type": "DATE_ONLY",
            "onChangeAction":{
              "allWidgetsAreRequired": true
            }
          }
        },
        {
          "textParagraph": {
            "text": "A datetime picker widget with just time:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_time_only",
            "label": "Select a time",
            "type": "TIME_ONLY"
          }
        }
      ]
    }
  ]
}
Defina uma ação allWidgetsAreRequired no menu suspenso.

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 1,
      "widgets": [
        {
          "selectionInput": {
            "name": "location",
            "label": "Select Color",
            "type": "DROPDOWN",
            "onChangeAction": {
              "allWidgetsAreRequired": true
            },
            "items": [
              {
                "text": "Red",
                "value": "red",
                "selected": false
              },
              {
                "text": "Green",
                "value": "green",
                "selected": false
              },
              {
                "text": "White",
                "value": "white",
                "selected": false
              },
              {
                "text": "Blue",
                "value": "blue",
                "selected": false
              },
              {
                "text": "Black",
                "value": "black",
                "selected": false
              }
            ]
          }
        }
      ]
    }
  ]
}

Definir a validação de um widget de entrada de texto

No campo de validação do widget textInput, é possível especificar o limite de caracteres e o tipo de entrada para esse widget de entrada de texto.

Definir um limite de caracteres para um widget de entrada de texto

JSON

{
  "sections": [
    {
      "header": "Tell us about yourself",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 2,
      "widgets": [
        {
          "textInput": {
            "name": "favoriteColor",
            "label": "Favorite color",
            "type": "SINGLE_LINE",
            "validation": {"characterLimit": 15},
            "onChangeAction":{
              "allWidgetsAreRequired": true
            }
          }
        }
      ]
    }
  ]
}
Definir o tipo de entrada para um widget de entrada de texto

JSON

{
  "sections": [
    {
      "header": "Validate text inputs by input types",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 2,
      "widgets": [
        {
          "textInput": {
            "name": "mailing_address",
            "label": "Please enter a valid email address",
            "type": "SINGLE_LINE",
            "validation": {
              "inputType": "EMAIL"
            },
            "onChangeAction": {
              "allWidgetsAreRequired": true
            }
          }
        },
        {
          "textInput": {
            "name": "validate_integer",
            "label": "Please enter a number",
              "type": "SINGLE_LINE",
            "validation": {
              "inputType": "INTEGER"
            }
          }
        },
        {
          "textInput": {
            "name": "validate_float",
            "label": "Please enter a number with a decimal",
            "type": "SINGLE_LINE",
            "validation": {
              "inputType": "FLOAT"
            }
          }
        }
      ]
    }
  ]
}

Resolver problemas

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: criar cards e caixas de diálogo interativos

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.

O código a seguir mostra um menu de seleção múltipla de itens de um conjunto externo de contatos para o usuário em um app do Chat que não é um complemento. O menu mostra um contato por padrão e executa a função getContacts para recuperar e preencher itens da fonte de dados externa:

Node.js

node/selection-input/index.js
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "getContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getContact("3")]
}

Python

python/selection-input/main.py
'selectionInput': {
  'name': "contacts",
  'type': "MULTI_SELECT",
  'label': "Selected contacts",
  'multiSelectMaxSelectedItems': 3,
  'multiSelectMinQueryLength': 1,
  'externalDataSource': { 'function': "getContacts" },
  # Suggested items loaded by default.
  # The list is static here but it could be dynamic.
  'items': [get_contact("3")]
}

Java

java/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("getContacts"))
  .setItems(List.of(getContact("3")))))))))));

Apps Script

apps-script/selection-input/selection-input.gs
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "getContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getContact("3")]
}

Para preencher automaticamente itens em um app do Chat que não é um complemento, crie uma função que consulte a fonte de dados externa e retorne itens sempre que um usuário digitar no menu de seleção múltipla. A função precisa:

  • Transmita um objeto de evento que represente a interação do usuário com o menu.
  • Identifique se o valor invokedFunction do evento de interação corresponde à função do campo externalDataSource.
  • Quando as funções corresponderem, retorne os itens sugeridos da fonte de dados externa. Para sugerir itens com base no que o usuário digita, use o valor da chave autocomplete_widget_query. Esse valor representa o que o usuário digita no menu.

O código a seguir preenche automaticamente itens de um recurso de dados externo. Usando o exemplo anterior, o app do Chat que não é um complemento sugere itens com base em quando a função getContacts é acionada:

Node.js

node/selection-input/index.js
/**
 * Responds to a WIDGET_UPDATE event in Google Chat.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  if (event.common["invokedFunction"] === "getContacts") {
    const query = event.common.parameters["autocomplete_widget_query"];
    return { actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: { suggestions: { items: [
        // The list is static here but it could be dynamic.
        getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("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 suggested item for selectors.
 */
function getContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Python

python/selection-input/main.py
def on_widget_update(event: dict) -> dict:
  """Responds to a WIDGET_UPDATE event in Google Chat."""
  if "getContacts" == event.get("common").get("invokedFunction"):
    query = event.get("common").get("parameters").get("autocomplete_widget_query")
    return { 'actionResponse': {
      'type': "UPDATE_WIDGET",
      'updatedWidget': { 'suggestions': { 'items': list(filter(lambda e: query is None or query in e["text"], [
        # The list is static here but it could be dynamic.
        get_contact("1"), get_contact("2"), get_contact("3"), get_contact("4"), get_contact("5")
      # Only return items based on the query from the user
      ]))}}
    }}


def get_contact(id: str) -> dict:
  """Generate a suggested contact given an ID."""
  return {
    'value': id,
    'startIconUri': "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    'text': "Contact " + id
  }

Java

java/selection-input/src/main/java/com/google/chat/selectionInput/App.java
// Responds to a WIDGET_UPDATE event in Google Chat.
Message onWidgetUpdate(JsonNode event) {
  if ("getContacts".equals(event.at("/invokedFunction").asText())) {
    String query = event.at("/common/parameters/autocomplete_widget_query").asText();
    return new Message().setActionResponse(new ActionResponse()
      .setType("UPDATE_WIDGET")
      .setUpdatedWidget(new UpdatedWidget()
        .setSuggestions(new SelectionItems().setItems(List.of(
          // The list is static here but it could be dynamic.
          getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
        // Only return items based on the query from the user
        ).stream().filter(e -> query == null || e.getText().indexOf(query) > -1).toList()))));
  }
  return null;
}

// Generate a suggested contact given an ID.
GoogleAppsCardV1SelectionItem getContact(String id) {
  return new GoogleAppsCardV1SelectionItem()
    .setValue(id)
    .setStartIconUri("https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png")
    .setText("Contact " + id);
}

Apps Script

apps-script/selection-input/selection-input.gs
/**
 * Responds to a WIDGET_UPDATE event in Google Chat.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  if (event.common["invokedFunction"] === "getContacts") {
    const query = event.common.parameters["autocomplete_widget_query"];
    return { actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: { suggestions: { items: [
        // The list is static here but it could be dynamic.
        getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("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 suggested item for selectors.
 */
function getContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}