Crea una página principal para una app de Google Chat

En esta página, se explica cómo compilar una página principal para los mensajes directos con tu app de Google Chat. Una página principal, a la que se hace referencia como página principal de la app en la API de Google Chat, es una interfaz de tarjeta personalizable que aparece en la pestaña Página principal de los espacios de mensajes directos 1:1 entre un usuario y una app de Chat.

Tarjeta de la página principal de la app con dos widgets.
Figura 1: Ejemplo de una página principal que aparece en los mensajes directos con una app de Chat.

A diferencia de otras aplicaciones host de Google Workspace, los complementos que extienden Chat no muestran una página principal en el panel de acceso rápido del lado derecho ni usan addOns.common.homepageTrigger en el manifiesto. En cambio, Chat muestra tu página principal como una tarjeta en la pestaña Página principal de un mensaje directo 1:1 con la app de Chat y se configura en la consola de Google Cloud.

Puedes usar la página principal de la app para compartir sugerencias para interactuar con la app de Chat, mostrar un panel personalizado del usuario o permitir que los usuarios accedan a un servicio o herramienta externos y los configuren desde Chat.

Usa Card Builder para diseñar y obtener una vista previa de las interfaces de usuario y los mensajes de las apps de Chat:

Abre Card Builder.

Requisitos previos

HTTP

Una app de Google Chat que recibe y responde a las interacciones del usuario. Para compilar uno, completa la guía de inicio rápido de HTTP.

Apps Script

Una app de Google Chat que recibe y responde a las interacciones del usuario. Para compilar una, completa la guía de inicio rápido de Apps Script.

Configura la página principal de la app de tu app de Chat

Para admitir la página principal de la app, habilita Support App Home y configura el activador de la página principal de la app en la consola de Google Cloud. Tu app de Chat recibe un evento de activación de página principal de la app cada vez que un usuario abre la pestaña Página principal en un mensaje directo 1:1 con la app de Chat.

Para configurar la página principal de la app en la consola de Google Cloud, sigue estos pasos:

  1. En la consola de Google Cloud, ve a Menú > APIs y servicios > APIs y servicios habilitados > API de Google Chat > Configuración.

    Ir a la configuración de la API de Chat

  2. En Funciones interactivas, asegúrate de que Habilitar funciones interactivas esté activado y, luego, en Funcionalidad, selecciona la casilla de verificación Admitir la página principal de la app.

  3. En Configuración de conexión > Activadores, especifica el controlador de la página principal de la app en el campo Página principal de la app según la arquitectura de tu app de chat:

    • HTTP: Ingresa la URL del extremo HTTPS que controla las solicitudes de la página principal de la app (o selecciona Usar una URL de extremo HTTP común para todos los activadores para que tu URL de extremo HTTP común reciba todos los eventos).
    • Google Apps Script: Ingresa el nombre de la función de devolución de llamada de Google Apps Script que compila y devuelve la tarjeta de la página principal (el valor predeterminado es onAppHome).

  4. Haz clic en Guardar.

Cómo controlar el objeto de evento de la página principal de la app

Cuando un usuario abre la pestaña Página principal de un mensaje directo 1:1 con tu app de Chat, Chat envía un objeto de evento a tu extremo de la página principal de la app o a la función de devolución de llamada.

A diferencia de los eventos de interacción con el espacio o los mensajes, el objeto de evento inicial de la página principal de la app no incluye una carga útil de interacción de unión (como messagePayload). Contiene los siguientes campos:

  • commonEventObject: Incluye clientPlatform, hostApp ("CHAT"), userLocale y userTimezone.
  • chat.user: Es el usuario de Chat que abrió la pestaña Inicio.
  • chat.eventTime: Es la marca de tiempo en la que el usuario abrió la pestaña Principal.

Cómo compilar una tarjeta de la página principal de la app

Cuando un usuario abre la pestaña Principal, controla el evento de activación de Página principal de la app devolviendo un objeto RenderActions con una acción de navegación pushCard y un Card. Para crear una experiencia interactiva, la tarjeta puede contener widgets interactivos, como botones o 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();
}

Responde a las interacciones de la página principal de la app

Si la tarjeta de la página principal de la app contiene widgets interactivos, como botones o entradas de formularios, cuando se hace clic en un botón, se envía un objeto de evento que contiene chat.buttonClickedPayload (junto con commonEventObject.parameters y commonEventObject.formInputs) a la función de acción o al extremo configurado del botón.

Para actualizar la tarjeta de la página principal de la app en respuesta a una interacción del usuario, devuelve un objeto RenderActions con una acción de navegación updateCard. Para obtener más información sobre cómo leer las entradas de formularios de widgets interactivos, consulta Cómo leer los datos de formularios que ingresan los usuarios en tarjetas.

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 diálogos desde la página principal de la app

Tu app de Chat también puede responder a las interacciones en la Página principal de la app abriendo diálogos.

Un diálogo con una variedad de widgets diferentes.
Figura 2: Un diálogo que le solicita al usuario que agregue un contacto.

Para obtener información sobre cómo abrir, actualizar y cerrar diálogos con RenderActions (pushCard, updateCard y endNavigation: "CLOSE_DIALOG"), consulta Cómo abrir diálogos interactivos.

Apps de Chat que no son complementos: Compila una página principal para una app de Chat

Si mantienes una app de Chat que no es un complemento de Google Workspace, Chat envía un evento de interacción APP_HOME cuando un usuario abre la pestaña Página principal y envía eventos de interacción CARD_CLICKED o SUBMIT_FORM cuando un usuario interactúa con widgets en la tarjeta de la página principal de la app.

Para actualizar una app de Chat que no es un complemento al framework de complementos de Google Workspace, consulta Cómo convertir una app de Google Chat en un complemento de Google Workspace.

Crea una tarjeta de página principal de la app en una app de Chat que no sea un complemento

En una app de Chat que no sea un complemento, controla el evento de interacción APP_HOME devolviendo una respuesta que contenga un campo renderActions de nivel superior con pushCard navegación:

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

En este ejemplo, se envía un mensaje de tarjeta devolviendo JSON de tarjeta. También puedes usar el servicio de tarjetas de 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"
      }}
    }]}}
  ]}]};
}

Responde a las interacciones de la página principal de la app en una app de Chat que no sea un complemento

En una app de Chat que no sea un complemento, controla los eventos de interacción CARD_CLICKED o SUBMIT_FORM de una tarjeta de la página principal de la app devolviendo una respuesta que contenga un campo renderActions de nivel superior con navegación 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

En este ejemplo, se envía un mensaje de tarjeta devolviendo JSON de tarjeta. También puedes usar el servicio de tarjetas de Apps Script.

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