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.
Use o Card Builder para criar e visualizar mensagens de cards JSON em apps de chat:
Abra o Criador de cards.Pré-requisitos
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
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 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:
Adicionar um menu suspenso
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 campoexternalDataSource
. - 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
Node.js
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 "Algo deu errado". ou "Não foi possível processar sua solicitação". Às vezes, a interface do Chat não exibe nenhuma mensagem de erro, mas o app ou o cartão do Chat 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 a corrigir erros quando o registro de erros para apps do Chat está ativado. Se precisar de ajuda para visualizar, depurar e corrigir erros, consulte Resolver problemas e corrigir erros do Google Chat.