Créer une page d'accueil pour une application Google Chat

Cette page explique comment créer une page d'accueil pour les messages privés avec votre application Google Chat. Une page d'accueil, appelée accueil de l'application dans l'API Google Chat, est une interface de fiche personnalisable qui s'affiche dans l'onglet Accueil des espaces de messages privés entre un utilisateur et une application Chat.

Fiche d'accueil de l'application avec deux widgets.
Figure 1 : Exemple de page d'accueil qui s'affiche dans les messages privés avec une application Chat.

Contrairement aux autres applications hôtes Google Workspace, les modules complémentaires qui étendent Chat n'affichent pas de page d'accueil dans le panneau d'accès rapide de droite et n'utilisent pas addOns.common.homepageTrigger dans le fichier manifeste. En revanche, Chat affiche votre page d'accueil sous forme de fiche dans l'onglet Accueil d'un message privé (1:1) avec l'application Chat. Elle est configurée dans la console Google Cloud.

Vous pouvez utiliser l'accueil de l'application pour partager des conseils sur l'interaction avec l'application Chat, afficher un tableau de bord utilisateur personnalisé ou permettre aux utilisateurs d'accéder à un service ou outil externe et de le configurer depuis Chat.


Utilisez Card Builder pour concevoir et prévisualiser les messages et les interfaces utilisateur des applications Chat :

Ouvrez le générateur de cartes.

Prérequis

HTTP

Application Google Chat qui reçoit les interactions utilisateur et y répond. Pour en créer un, suivez le guide de démarrage rapide HTTP.

Apps Script

Application Google Chat qui reçoit les interactions utilisateur et y répond. Pour en créer un, suivez le guide de démarrage rapide Apps Script.

Configurer l'accueil de l'application pour votre application Chat

Pour prendre en charge la page d'accueil de l'application, activez l'option Support App Home (Prendre en charge la page d'accueil de l'application) et configurez le déclencheur App home (Page d'accueil de l'application) dans la console Google Cloud. Votre application Chat reçoit un événement de déclenchement Accueil de l'application chaque fois qu'un utilisateur ouvre l'onglet Accueil dans un message privé avec l'application Chat.

Pour configurer la page d'accueil de l'application dans la console Google Cloud :

  1. Dans la console Google Cloud, accédez à Menu > API et services > API et services activés > API Google Chat > Configuration.

    Accéder à la configuration de l'API Chat

  2. Sous Fonctionnalités interactives, assurez-vous que l'option Activer les fonctionnalités interactives est activée, puis sous Fonctionnalité, cochez la case Accueil de l'application d'assistance.

  3. Sous Paramètres de connexion > Déclencheurs, spécifiez votre gestionnaire App Home dans le champ App Home en fonction de l'architecture de votre application de chat :

    • HTTP : saisissez l'URL du point de terminaison HTTPS qui gère les requêtes de la page d'accueil de l'application (ou sélectionnez Utiliser une URL de point de terminaison HTTP commune pour tous les déclencheurs afin que votre URL de point de terminaison HTTP commune reçoive tous les événements).
    • Google Apps Script : saisissez le nom de la fonction de rappel Google Apps Script qui crée et renvoie la fiche de votre page d'accueil (la valeur par défaut est onAppHome).
  4. Cliquez sur Enregistrer.

Gérer l'objet d'événement App Home

Lorsqu'un utilisateur ouvre l'onglet Accueil d'un message privé avec votre application Chat, Chat envoie un objet d'événement à votre point de terminaison ou fonction de rappel de l'accueil de l'application.

Contrairement aux événements d'interaction avec un espace ou un message, l'objet d'événement initial de l'accueil de l'application n'inclut pas de charge utile d'interaction d'union (telle que messagePayload). Il contient les champs suivants :

  • commonEventObject : inclut clientPlatform, hostApp ("CHAT"), userLocale et userTimezone.
  • chat.user : utilisateur Chat ayant ouvert l'onglet Accueil.
  • chat.eventTime : code temporel indiquant le moment où l'utilisateur a ouvert l'onglet Accueil.

Créer une carte App Home

Lorsqu'un utilisateur ouvre l'onglet Accueil, gérez l'événement de déclenchement Accueil de l'application en renvoyant un objet RenderActions avec une action de navigation pushCard et un Card. Pour créer une expérience interactive, la fiche peut contenir des widgets interactifs tels que des boutons ou des champs de saisie de texte.

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();
}

Répondre aux interactions avec l'accueil de l'application

Si la carte de votre application contient des widgets interactifs, tels que des boutons ou des champs de formulaire, un clic sur un bouton envoie un objet d'événement contenant chat.buttonClickedPayload (ainsi que commonEventObject.parameters et commonEventObject.formInputs) à la fonction ou au point de terminaison d'action configurés du bouton.

Pour mettre à jour la fiche "Accueil de l'application" en réponse à une interaction de l'utilisateur, renvoyez un objet RenderActions avec une action de navigation updateCard. Pour en savoir plus sur la lecture des entrées de formulaire à partir de widgets interactifs, consultez Lire les données de formulaire saisies par les utilisateurs sur les fiches.

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();
}

Ouvrir des boîtes de dialogue depuis l'accueil de l'application

Votre application Chat peut également répondre aux interactions dans l'accueil de l'application en ouvrant des boîtes de dialogue.

Boîte de dialogue comportant différents widgets.
Figure 2 : Boîte de dialogue invitant l'utilisateur à ajouter un contact.

Pour savoir comment ouvrir, mettre à jour et fermer des boîtes de dialogue à l'aide de RenderActions (pushCard, updateCard et endNavigation: "CLOSE_DIALOG"), consultez Ouvrir des boîtes de dialogue interactives.

Applications Chat qui ne sont pas des modules complémentaires : créer une page d'accueil pour une application Chat

Si vous gérez une application Chat qui n'est pas un module complémentaire Google Workspace, Chat envoie un événement d'interaction APP_HOME lorsqu'un utilisateur ouvre l'onglet Accueil, et envoie des événements d'interaction CARD_CLICKED ou SUBMIT_FORM lorsqu'un utilisateur interagit avec des widgets sur la fiche "Accueil de l'application".

Pour migrer une application Chat qui n'est pas un module complémentaire vers le framework de modules complémentaires Google Workspace, consultez Convertir une application Google Chat en module complémentaire Google Workspace.

Créer une fiche "Accueil de l'application" dans une application Chat qui n'est pas un module complémentaire

Dans une application Chat qui n'est pas un module complémentaire, gérez l'événement d'interaction APP_HOME en renvoyant une réponse contenant un champ renderActions de premier niveau avec la navigation pushCard :

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

Cet exemple envoie un message de carte en renvoyant le code JSON de la carte. Vous pouvez également utiliser le service de cartes 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"
      }}
    }]}}
  ]}]};
}

Répondre aux interactions avec la page d'accueil de l'application dans une application Chat qui n'est pas un module complémentaire

Dans une application Chat qui n'est pas un module complémentaire, gérez les événements d'interaction CARD_CLICKED ou SUBMIT_FORM à partir d'une fiche d'accueil de l'application en renvoyant une réponse contenant un champ renderActions de premier niveau avec la navigation 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

Cet exemple envoie un message de carte en renvoyant le code JSON de la carte. Vous pouvez également utiliser le service de cartes Apps Script.

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