Criar a página inicial de um app do Google Chat

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.

Card inicial do app com dois widgets.
Figura 1: exemplo de uma página inicial que aparece em mensagens diretas com um app de 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 Builder

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 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:

  1. No console do Google Cloud, acesse Menu > APIs e serviços > APIs e serviços ativados > API Google Chat > Configuração.

    Acessar a configuração da API Chat

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

  3. 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).
  4. 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: inclui clientPlatform, hostApp ("CHAT"), userLocale e userTimezone.
  • 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.

Uma caixa de diálogo com vários widgets diferentes.
Figura 2: uma caixa de diálogo que pede ao usuário para adicionar um contato.

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.

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

node/app-home/index.js
app.post('/', async (req, res) => {
  let event = req.body.chat;

  let body = {};
  if (event.type === 'APP_HOME') {
    // App home is requested
    body = { action: { navigations: [{
      pushCard: getHomeCard()
    }]}}
  } else if (event.type === 'SUBMIT_FORM') {
    // The update button from app home is clicked
    commonEvent = req.body.commonEventObject;
    if (commonEvent && commonEvent.invokedFunction === 'updateAppHome') {
      body = updateAppHome()
    }
  }

  return res.json(body);
});

// Create the app home card
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Python

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

  Returns:
      Mapping[str, Any]: the response
  """
  event = request.get_json()
  match event['chat'].get('type'):

    case 'APP_HOME':
      # App home is requested
      body = { "action": { "navigations": [{
        "pushCard": get_home_card()
      }]}}

    case 'SUBMIT_FORM':
      # The update button from app home is clicked
      event_object = event.get('commonEventObject')
      if event_object is not None:
        if 'update_app_home' == event_object.get('invokedFunction'):
          body = update_app_home()

    case _:
      # Other response types are not supported
      body = {}

  return json.jsonify(body)


def get_home_card() -> Mapping[str, Any]:
  """Create the app home card

  Returns:
      Mapping[str, Any]: the card
  """
  return { "sections": [{ "widgets": [
    { "textParagraph": {
      "text": "Here is the app home 🏠 It's " +
        datetime.datetime.now().isoformat()
    }},
    { "buttonList": { "buttons": [{
      "text": "Update app home",
      "onClick": { "action": {
        "function": "update_app_home"
      }}
    }]}}
  ]}]}

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java
// Process Google Chat events
@PostMapping("/")
@ResponseBody
public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
  switch (event.at("/chat/type").asText()) {
    case "APP_HOME":
      // App home is requested
      GenericJson navigation = new GenericJson();
      navigation.set("pushCard", getHomeCard());

      GenericJson action = new GenericJson();
      action.set("navigations", List.of(navigation));

      GenericJson response = new GenericJson();
      response.set("action", action);
      return response;
    case "SUBMIT_FORM":
      // The update button from app home is clicked
      if (event.at("/commonEventObject/invokedFunction").asText().equals("updateAppHome")) {
        return updateAppHome();
      }
  }

  return new GenericJson();
}

// Create the app home card
GoogleAppsCardV1Card getHomeCard() {
  return new GoogleAppsCardV1Card()
    .setSections(List.of(new GoogleAppsCardV1Section()
      .setWidgets(List.of(
        new GoogleAppsCardV1Widget()
          .setTextParagraph(new GoogleAppsCardV1TextParagraph()
            .setText("Here is the app home 🏠 It's " + new Date())),
        new GoogleAppsCardV1Widget()
          .setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
            .setText("Update app home")
            .setOnClick(new GoogleAppsCardV1OnClick()
              .setAction(new GoogleAppsCardV1Action()
                .setFunction("updateAppHome"))))))))));
}

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.

apps-script/app-home/app-home.gs
/**
 * Responds to a APP_HOME event in Google Chat.
 */
function onAppHome() {
  return { action: { navigations: [{
    pushCard: getHomeCard()
  }]}};
}

/**
 * Returns the app home card.
 */
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

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

node/app-home/index.js
// Update the app home
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}}
};

Python

python/app-home/main.py
def update_app_home() -> Mapping[str, Any]:
  """Update the app home

  Returns:
      Mapping[str, Any]: the update card render action
  """
  return { "renderActions": { "action": { "navigations": [{
    "updateCard": get_home_card()
  }]}}}

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java
// Update the app home
GenericJson updateAppHome() {
  GenericJson navigation = new GenericJson();
  navigation.set("updateCard", getHomeCard());

  GenericJson action = new GenericJson();
  action.set("navigations", List.of(navigation));

  GenericJson renderActions = new GenericJson();
  renderActions.set("action", action);

  GenericJson response = new GenericJson();
  response.set("renderActions", renderActions);
  return response;
}

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.

apps-script/app-home/app-home.gs
/**
 * Updates the home app.
 */
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}};
}