Criar um cartão interativo ou uma caixa de diálogo

Nesta página, explicamos como adicionar widgets e elementos da interface a mensagens de cards ou caixas de diálogo para que os usuários possam interagir com o app Google Chat, seja clicando em um botão ou enviando informações.


Crie e visualize cards com o Criador de cards.

Abra o Criador de cards.

Pré-requisitos

  • Uma conta do Google Workspace com acesso ao Google Chat.
  • Um app do Chat publicado. Para criar um app do Chat, siga este quickstart.
  • Adicionar um botão

    O widget ButtonList exibe um conjunto de botões. Os botões podem exibir texto, um ícone ou ambos, texto e ícone. 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 aos usuários mais informações.
    • Execute um action que executa uma função personalizada, como chamar uma API.

    Para acessibilidade, os botões oferecem suporte a texto alternativo.

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

    Confira 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 cor personalizada e um botão desativado

    Você pode impedir que os usuários cliquem em um botão configurando "disabled": "true".

    A seguir, um card que consiste em um widget ButtonList com dois botões é exibido. Um deles usa o campo Color para personalizar a cor do plano de fundo. 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

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

    Adicionar um botão com um ícone e texto

    Veja a seguir um cartão que consiste em 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 texto. O usuário pode clicar no ícone ou botão de texto para executar a função sendEmail.

    Adicionar elementos de interface selecionáveis

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

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

    Os apps de chat podem receber e processar o valor de itens selecionados. Para detalhes sobre como trabalhar com entradas de formulário, consulte Receber dados de formulário.

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

    Adicionar uma caixa de seleção

    Confira a seguir uma caixa de diálogo que solicita que o usuário especifique se um contato é profissional, pessoal ou ambos, com um widget SelectionInput que usa caixas de seleção:

    Adicionar um botão de opção

    Confira a seguir uma caixa de diálogo 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

    Veja a seguir uma caixa de diálogo que solicita que o usuário especifique se um contato é profissional, pessoal ou ambos com um widget SelectionInput que usa chaves:

    Veja a seguir uma caixa de diálogo que solicita que o usuário especifique se um contato é profissional ou pessoal com um widget SelectionInput que usa um menu suspenso:

    Adicionar um menu de seleção múltipla

    Veja a seguir uma caixa de diálogo que solicita que o usuário selecione contatos em um menu de seleção múltipla:

    Usar fontes de dados para menus de seleção múltipla

    A seção a seguir explica como usar menus de seleção múltipla para preencher dados de fontes dinâmicas, como um aplicativo do Google Workspace ou uma fonte de dados externa.

    Fontes de dados do Google Workspace

    É possível preencher itens para um menu de seleção múltipla com base nas 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 inserir itens no menu de seleção múltipla só poderá ver e selecionar os espaços a que pertencem na organização do Google Workspace.

    Para usar fontes de dados do Google Workspace, especifique o campo platformDataSource. Ao contrário de outros tipos de entrada de seleção, você omite objetos SectionItem, porque esses itens de seleção são extraídos 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 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
              }
            }
          }
        }
      }
    }
    
    Origens de dados fora do Google Workspace

    Os menus de seleção múltipla também podem preencher itens de uma fonte de dados externa ou de terceiros. Por exemplo, é possível usar menus de seleção múltipla para ajudar um usuário a selecionar de 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 a uma fonte de dados externa, você pode incluir itens sugeridos que aparecem no menu de seleção múltipla antes de os usuários digitarem no menu. Por exemplo, é possível preencher contatos pesquisados recentemente para o usuário. Para preencher os itens sugeridos usando uma fonte de dados externa, especifique objetos SelectionItem.

    O código abaixo mostra um menu de seleção múltipla de itens de um conjunto externo de contatos para o usuário. O menu exibe um contato por padrão e executa a função getContacts para recuperar e preencher itens da fonte de dados externa:

    JSON

    {
      "selectionInput": {
        "name": "contacts",
        "type": "MULTI_SELECT",
        "label": "Selected contacts",
        "multiSelectMaxSelectedItems": 5,
        "multiSelectMinQueryLength": 2,
        "externalDataSource": {
          "function": "getContacts"
        },
        "items": [
          {
            "text": "Contact 3",
            "value": "contact-3",
            "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
            "bottomText": "Contact three description",
            "selected": false
          }
        ]
      }
    }
    

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

    Para preencher itens automaticamente, 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 fazer o seguinte:

    • 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 itens sugeridos da fonte de dados externa. Para sugerir itens com base no que o usuário digita, acesse 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 sugere itens com base em quando a função getContacts é acionada:

    Apps Script

    apps-script/selection-input/on-widget-update.gs
    /**
     * Widget update event handler.
     *
     * @param {Object} event The event object from Chat API.
     * @return {Object} Response from the Chat app.
     */
    function onWidgetUpdate(event) {
      const actionName = event.common["invokedFunction"];
      if (actionName !== "getContacts") {
        return {};
      }
    
      return {
        actionResponse: {
          type: "UPDATE_WIDGET",
          updatedWidget: {
            suggestions: {
              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
                },
              ]
            }
          }
        }
      };
    }
    

    Node.js

    node/selection-input/on-widget-update.js
    /**
     * Widget update event handler.
     *
     * @param {Object} event The event object from Chat API.
     * @return {Object} Response from the Chat app.
     */
    function onWidgetUpdate(event) {
      const actionName = event.common["invokedFunction"];
      if (actionName !== "getContacts") {
        return {};
      }
    
      return {
        actionResponse: {
          type: "UPDATE_WIDGET",
          updatedWidget: {
            suggestions: {
              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
                },
              ]
            }
          }
        }
      };
    }
    

    Adicionar um campo em que o usuário pode inserir texto

    O widget TextInput fornece um campo em que os usuários podem inserir texto. O widget oferece suporte a 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, como quando um usuário adiciona ou exclui texto.

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

    Para processar o texto inserido pelos usuários, consulte Receber dados do formulário.

    A seguir, um card que consiste em um widget TextInput:

    Permitir que um usuário escolha uma data e hora

    O widget DateTimePicker permite que os usuários insiram uma data, uma hora ou uma data e uma hora. Os usuários também 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.

    Para processar os valores de data e hora inseridos pelos usuários, consulte Receber dados do formulário.

    Veja a seguir um card que consiste em três tipos diferentes de widgets DateTimePicker:

    Resolver problemas

    Quando um app ou card do Google Chat retorna um erro, a interface do Chat mostra a mensagem "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 card do Chat produz um resultado inesperado. Por exemplo, uma mensagem de card pode não aparecer.

    Embora uma mensagem de erro não apareça na interface do Chat, mensagens de erro descritivas e dados de registro estão disponíveis para ajudar a corrigir erros quando o registro de erros dos apps do Chat está ativado. Se precisar de ajuda para visualizar, depurar e corrigir erros, consulte Resolver problemas e corrigir erros do Google Chat.