Nesta página, explicamos como criar uma página inicial para mensagens diretas com seu app do Google Chat. Uma página inicial, chamada de página inicial do app na API do Google Chat, é uma interface de card personalizável que aparece na guia Início dos espaços de mensagens diretas individuais entre um usuário e um app do Chat.
Ao contrário de outros aplicativos host do Google Workspace, os complementos que
estendem o Chat não mostram uma página inicial no painel de acesso
rápido à direita e não usam addOns.common.homepageTrigger no manifesto.
Em vez disso, o Chat mostra sua página inicial como um card na guia Início de uma mensagem direta individual com o app do Chat, e ela é configurada no console do Google Cloud.
É possível usar a página inicial do app para compartilhar dicas de interação com o app Chat, mostrar um painel personalizado do usuário ou permitir que os usuários acessem e configurem um serviço ou ferramenta externa no Chat.
Use o Card Builder para criar e visualizar mensagens e interfaces de usuário para apps do Chat:
Abra o Card BuilderPré-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 do 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.
Configurar a página inicial do app para seu app do Chat
Para oferecer suporte à página inicial do app, ative a opção Suporte à página inicial do app e configure o gatilho da Página inicial do app no console do Google Cloud. O app do Chat recebe um evento de acionamento da página inicial do app sempre que um usuário abre a guia Início em uma mensagem direta individual com o app do Chat.
Para configurar a página inicial do app no console do Google Cloud:
No console do Google Cloud, acesse Menu > APIs e serviços > APIs e serviços ativados > API Google Chat > Configuração.
Em Recursos interativos, verifique se a opção Ativar recursos interativos está ativada e, em Funcionalidade, marque a caixa de seleção Suporte à página inicial do app.
Em Configurações de conexão > Acionadores, especifique seu manipulador da página inicial do app no campo Página inicial do app com base na arquitetura do seu app de chat:
- HTTP: insira o URL do endpoint HTTPS que processa as solicitações da página inicial do app ou selecione Usar um URL de endpoint HTTP comum para todos os gatilhos para que seu URL de endpoint HTTP comum receba todos os eventos.
- Google Apps Script: insira o nome da função de callback do Google Apps Script que cria e retorna o card da página inicial (o padrão é
onAppHome).
Clique em Salvar.
Processar o objeto de evento da página inicial do app
Quando um usuário abre a guia Início de uma mensagem direta individual com seu app Chat, o Chat envia um objeto de evento para o endpoint da página inicial do app ou a função de callback.
Ao contrário dos eventos de interação de espaço ou mensagem, o objeto de evento inicial da página inicial do app
não inclui um payload de interação de união (como messagePayload). Ele
contém os seguintes campos:
commonEventObject: incluiclientPlatform,hostApp("CHAT"),userLocaleeuserTimezone.chat.user: o usuário do Chat que abriu a guia Início.chat.eventTime: o carimbo de data/hora em que o usuário abriu a guia Início.
Criar um card da página inicial do app
Quando um usuário abrir a guia Início, processe o evento de acionamento Início do app retornando um objeto RenderActions com uma ação de navegação pushCard e um Card. Para criar uma experiência interativa, o card pode conter widgets interativos, como botões ou entradas de texto.
HTTP
{
"action": {
"navigations": [
{
"pushCard": {
"header": {
"title": "Welcome to App Home"
},
"sections": [
{
"widgets": [
{
"textParagraph": {
"text": "Manage your settings and view your dashboard here."
}
},
{
"buttonList": {
"buttons": [
{
"text": "Refresh",
"onClick": {
"action": {
"function": "https://example.com/updateAppHome"
}
}
}
]
}
}
]
}
]
}
}
]
}
}
Apps Script
/**
* Builds and returns the App Home card when a user opens the Home tab.
*
* @param {Object} event The event object from Google Chat.
* @return {ActionResponse} The RenderActions response pushing the homepage card.
*/
function onAppHome(event) {
const card = CardService.newCardBuilder()
.setHeader(
CardService.newCardHeader().setTitle('Welcome to App Home'))
.addSection(
CardService.newCardSection()
.addWidget(
CardService.newTextParagraph().setText(
'Manage your settings and view your dashboard here.'))
.addWidget(
CardService.newButtonSet().addButton(
CardService.newTextButton()
.setText('Refresh')
.setOnClickAction(
CardService.newAction().setFunctionName(
'updateAppHome')))))
.build();
return CardService.newActionResponseBuilder()
.setNavigation(CardService.newNavigation().pushCard(card))
.build();
}
Responder às interações do App Home
Se o card da página inicial do app tiver widgets interativos, como botões ou entradas de formulário, clicar em um botão vai enviar um objeto de evento contendo chat.buttonClickedPayload (junto com commonEventObject.parameters e commonEventObject.formInputs) para a função de ação ou o endpoint configurado do botão.
Para atualizar o card da página inicial do app em resposta a uma interação do usuário, retorne um objeto RenderActions com uma ação de navegação updateCard. Para saber mais sobre como ler entradas de formulário de widgets interativos, consulte Ler dados de formulário inseridos pelos usuários em cards.
HTTP
{
"action": {
"navigations": [
{
"updateCard": {
"header": {
"title": "Welcome to App Home"
},
"sections": [
{
"widgets": [
{
"textParagraph": {
"text": "Last updated: 2026-10-02T23:00:00Z"
}
}
]
}
]
}
}
]
}
}
Apps Script
/**
* Updates the App Home card when a user clicks the Refresh button.
*
* @param {Object} event The event object from Google Chat.
* @return {ActionResponse} The RenderActions response updating the homepage card.
*/
function updateAppHome(event) {
const updatedCard = CardService.newCardBuilder()
.setHeader(
CardService.newCardHeader().setTitle('Welcome to App Home'))
.addSection(
CardService.newCardSection().addWidget(
CardService.newTextParagraph().setText(
'Last updated: ' + new Date().toTimeString())))
.build();
return CardService.newActionResponseBuilder()
.setNavigation(CardService.newNavigation().updateCard(updatedCard))
.build();
}
Abrir caixas de diálogo na página inicial do app
Seu app do Chat também pode responder a interações na página inicial do app abrindo caixas de diálogo.
Para saber como abrir, atualizar e fechar caixas de diálogo usando RenderActions
(pushCard, updateCard e endNavigation: "CLOSE_DIALOG"), consulte
Abrir caixas de diálogo interativas.
Temas relacionados
- Receber e responder a interações do usuário
- Abrir caixas de diálogo interativas
- Ler dados de formulários inseridos pelos usuários em cards
- Conferir exemplos de apps do Chat
Apps do Chat que não são complementos: criar uma página inicial para um app do Chat
Se você mantiver um app do Chat que não seja um
complemento do Google Workspace, o Chat enviará um
evento de interação APP_HOME
quando um usuário abrir a guia Início e enviará eventos de interação CARD_CLICKED ou SUBMIT_FORM
quando um usuário interagir com widgets no card da página inicial do app.
Para fazer upgrade de um app do Chat que não é um complemento para a estrutura de complementos do Google Workspace, consulte Converter um app do Google Chat em um complemento do Google Workspace.
Criar um card da página inicial do app em um app do Chat que não seja um complemento
Em um app do Chat que não é um
complemento, processe o evento de interação APP_HOME retornando uma resposta que contenha um campo renderActions de nível superior com
pushCard navegação:
Node.js
Python
Java
Apps Script
Este exemplo envia uma mensagem de card retornando JSON do card. Você também pode usar o serviço de card do Apps Script.
Responder a interações da página inicial do app em um app do Chat que não é um complemento
Em um app do Chat que não seja um
complemento, processe eventos de interação CARD_CLICKED ou SUBMIT_FORM
de um card da página inicial do app retornando uma resposta que contenha um
campo renderActions de nível superior com navegação updateCard:
Node.js
Python
Java
Apps Script
Este exemplo envia uma mensagem de card retornando JSON do card. Você também pode usar o serviço de card do Apps Script.