Startseite für eine Google Chat-App erstellen

Auf dieser Seite wird beschrieben, wie Sie eine Startseite für Direktnachrichten mit Ihrer Google Chat-App erstellen. Eine Startseite, in der Google Chat API als App Home bezeichnet, ist eine anpassbare Kartenschnittstelle, die auf dem Tab Startseite von 1:1-Direktnachrichtengruppenbereichen zwischen einem Nutzer und einer Chat-App angezeigt wird.

Abbildung 1: Beispiel für eine Startseite, die in Direktnachrichten mit einer Chat-App angezeigt wird.

Im Gegensatz zu anderen Google Workspace-Hostanwendungen wird für Add-ons, die Chat erweitern, keine Startseite im Schnellzugriffsfeld auf der rechten Seite angezeigt und addOns.common.homepageTrigger wird nicht im Manifest verwendet. Stattdessen wird Ihre Startseite in Chat als Karte auf dem Tab Startseite einer 1:1-Direktnachricht mit der Chat App angezeigt und in der Google Cloud Console konfiguriert.

Sie können das App-Startseite verwenden, um Tipps für die Interaktion mit der Chat-App zu teilen, ein personalisiertes Nutzer-Dashboard anzuzeigen oder Nutzern den Zugriff auf und die Konfiguration eines externen Dienstes oder Tools über Chat zu ermöglichen.

---

Mit dem Card Builder können Sie Nachrichten und Benutzeroberflächen für Chat-Apps entwerfen und in der Vorschau ansehen:

Card Builder öffnen

---

Vorbereitung

HTTP

Eine Google Chat-App, die Nutzerinteraktionen empfängt und darauf reagiert. Kurzanleitung für HTTP

Hinweis:Die Codebeispiele in dieser Anleitung sind für die Ausführung als Google Cloud Run-Funktion für Node.js geschrieben.

Apps Script

Eine Google Chat-App, die Nutzerinteraktionen empfängt und darauf reagiert. Apps Script-Kurzanleitung

App-Startseite für Ihre Chat-App konfigurieren

Um App Home zu unterstützen, aktiviere App Home unterstützen und konfiguriere den App Home-Trigger in der Google Cloud Console. Ihre Chat-App empfängt ein App-Startseite-Triggerereignis, wenn ein Nutzer den Tab Startseite in einer 1:1-Direktnachricht mit der Chat-App öffnet.

So konfigurieren Sie App Home in der Google Cloud Console:

1. Rufen Sie in der Google Cloud Console das Menü > APIs und Dienste > Aktivierte APIs und Dienste > Google Chat API > Konfiguration auf.

   Zur Chat API-Konfiguration

2. Achten Sie darauf, dass unter Interaktive Funktionen die Option Interaktive Funktionen aktivieren aktiviert ist. Aktivieren Sie dann unter Funktionsweise das Kästchen App-Startseite unterstützen.

3. Geben Sie unter Verbindungseinstellungen > Auslöser den App-Home-Handler im Feld App-Home basierend auf der Architektur Ihrer Chat-App an:

   • HTTP: Geben Sie die HTTPS-Endpunkt-URL ein, die App Home-Anfragen verarbeitet, oder wählen Sie Gemeinsame HTTP-Endpunkt-URL für alle Trigger verwenden aus, damit alle Ereignisse an Ihre gemeinsame HTTP-Endpunkt-URL gesendet werden.
   • Google Apps Script: Geben Sie den Namen der Google Apps Script-Callback-Funktion ein, mit der die Startseitenkarte erstellt und zurückgegeben wird (Standardwert: onAppHome).

4. Klicken Sie auf Speichern.

App Home-Ereignisobjekt verarbeiten

Wenn ein Nutzer den Tab Startseite einer 1:1-Direktnachricht mit Ihrer Chat-App öffnet, sendet Chat ein Ereignisobjekt an den App-Startseiten-Endpunkt oder die Callback-Funktion.

Im Gegensatz zu Ereignissen für Interaktionen mit Gruppenbereichen oder Nachrichten enthält das erste App Home-Ereignisobjekt keine Nutzlast für die Union-Interaktion (z. B. messagePayload). Es enthält die folgenden Felder:

• commonEventObject: Enthält clientPlatform, hostApp ("CHAT"), userLocale und userTimezone.
• chat.user: Der Chat-Nutzer, der den Tab Startseite geöffnet hat.
• chat.eventTime: Der Zeitstempel, der angibt, wann der Nutzer den Tab Startseite geöffnet hat.

Karte für die Startseite der App erstellen

Wenn ein Nutzer den Tab Zuhause öffnet, müssen Sie das Triggerereignis App Home verarbeiten, indem Sie ein RenderActions-Objekt mit einer pushCard-Navigationsaktion und einem Card zurückgeben. Um eine interaktive Umgebung zu schaffen, kann die Karte interaktive Widgets wie Schaltflächen oder Texteingaben enthalten.

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

Auf App Home-Interaktionen reagieren

Wenn die App Home-Karte interaktive Widgets wie Schaltflächen oder Formulareingaben enthält, wird durch Klicken auf eine Schaltfläche ein Ereignisobjekt mit chat.buttonClickedPayload (sowie commonEventObject.parameters und commonEventObject.formInputs) an die für die Schaltfläche konfigurierte Aktionsfunktion oder den Endpunkt gesendet.

Wenn Sie die App-Startseite-Karte als Reaktion auf eine Nutzerinteraktion aktualisieren möchten, geben Sie ein RenderActions-Objekt mit einer updateCard-Navigationsaktion zurück. Weitere Informationen zum Lesen von Formulareingaben aus interaktiven Widgets finden Sie unter Von Nutzern eingegebene Formulardaten auf Karten lesen.

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

Dialogfelder über das App-Startfeld öffnen

Ihre Chat-App kann auch auf Interaktionen in App Home reagieren, indem sie Dialogfelder öffnet.

Abbildung 2: Ein Dialogfeld, in dem ein Nutzer aufgefordert wird, einen Kontakt hinzuzufügen.

Informationen zum Öffnen, Aktualisieren und Schließen von Dialogfeldern mit RenderActions (pushCard, updateCard und endNavigation: "CLOSE_DIALOG") finden Sie unter Interaktive Dialogfelder öffnen.

Weitere Informationen

• Nutzerinteraktionen empfangen und darauf reagieren
• Interaktive Dialogfelder öffnen
• Von Nutzern in Karten eingegebene Formulardaten lesen
• Chat-App-Beispiele ansehen

Chat-Apps, die keine Add‑ons sind: Startseite für eine Chat-App erstellen

Wenn Sie eine Chat-App verwalten, die kein Google Workspace-Add-on ist, sendet Chat ein APP_HOME-Interaktionsereignis, wenn ein Nutzer den Tab Startseite öffnet, und CARD_CLICKED- oder SUBMIT_FORM-Interaktionsereignisse, wenn ein Nutzer mit Widgets auf der App-Startseite interagiert.

Wenn Sie eine Chat-App, die kein Add‑on ist, auf das Google Workspace-Add‑on-Framework umstellen möchten, lesen Sie den Abschnitt Google Chat-App in ein Google Workspace-Add‑on umwandeln.

App-Startseite in einer Chat-App erstellen, die kein Add‑on ist

In einer Chat-App, die kein Add-on ist, müssen Sie das APP_HOME-Interaktionsereignis verarbeiten, indem Sie eine Antwort mit einem renderActions-Feld der obersten Ebene mit pushCard-Navigation zurückgeben:

Node.js

node/app-home/index.js

Auf GitHub ansehen

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

Auf GitHub ansehen

@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

Auf GitHub ansehen

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

In diesem Beispiel wird eine Kartenmitteilung gesendet, indem Karten-JSON zurückgegeben wird. Sie können auch den Apps Script-Kartendienst verwenden.

apps-script/app-home/app-home.gs

Auf GitHub ansehen

/**
 * 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"
      }}
    }]}}
  ]}]};
}

Auf App Home-Interaktionen in einer Chat-App antworten, die kein Add‑on ist

Verarbeiten Sie in einer Chat-App, die kein Add-on ist, CARD_CLICKED- oder SUBMIT_FORM-Interaktionsereignisse von einer App-Startseite-Karte, indem Sie eine Antwort mit einem renderActions-Feld der obersten Ebene mit updateCard-Navigation zurückgeben:

Node.js

node/app-home/index.js

Auf GitHub ansehen

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

Python

python/app-home/main.py

Auf GitHub ansehen

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

Auf GitHub ansehen

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

In diesem Beispiel wird eine Kartenmitteilung gesendet, indem Karten-JSON zurückgegeben wird. Sie können auch den Apps Script-Kartendienst verwenden.

apps-script/app-home/app-home.gs

Auf GitHub ansehen

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