Kontakte in Google Chat erfassen und verwalten

In diesem Tutorial erfahren Sie, wie Sie eine Google Chat-App erstellen, mit der Google Chat-Nutzer ihre privaten und geschäftlichen Kontakte verwalten können. Um Informationen zu sammeln, fordert die Chat-App Nutzer auf, ein Kontaktformular in Kartenmitteilungen und Dialogfeldern auszufüllen.

So sieht die Chat App in Aktion aus:

Vorbereitung

• Ein Google Workspace-Konto für Unternehmen oder Enterprise mit Zugriff auf Google Chat.
• Google Cloud-Projekt erstellen

Ziele

• Benutzeroberflächen (UIs) als card-Objekte entwerfen und erstellen und die UIs in Nachrichten und Dialogfeldern anzeigen.
• Informationen empfangen und verarbeiten, die Nutzer über Widgets für die Formulareingabe senden.
• Auf Befehle antworten mit Nachrichten, die Text, Karten und Zubehör-Widgets enthalten.

Architektur

Die Chat-App basiert auf Google Apps Script (als Google Workspace-Add-on, das Google Chat erweitert) und reagiert auf Nutzerinteraktionen (onMessage, onAppCommand und Schaltflächenklicks, die openInitialDialog, openConfirmationDialog und submitForm aufrufen), um Chat-Nutzer zu verarbeiten und auf sie zu reagieren.

So interagiert ein Nutzer in der Regel mit der Chat App:

1. Ein Nutzer öffnet eine Direktnachricht mit der Chat-App oder fügt die Chat-App einem vorhandenen Gruppenbereich hinzu.

2. Die Chat-App fordert den Nutzer auf, einen Kontakt hinzuzufügen, indem sie ein Kontaktformular als card-Objekt erstellt und anzeigt. So reagiert die Chat App auf Nutzer, wenn das Kontaktformular angezeigt wird:

   • Antwortet auf @Erwähnungen und Direktnachrichten (onMessage) mit einer Kartenmitteilung, die das Kontaktformular enthält.
   • Reagiert auf den Slash-Befehl /addContact (onAppCommand), indem ein Dialogfeld mit dem Kontaktformular geöffnet wird.
   • Antwortet auf den Slash-Befehl /about (onAppCommand) mit einer Textnachricht, die den Button Kontakt hinzufügen enthält. Nutzer können darauf klicken, um openInitialDialog aufzurufen und ein Dialogfeld mit dem Kontaktformular zu öffnen.

3. Wenn das Kontaktformular angezeigt wird, gibt der Nutzer Kontaktdaten in die folgenden Felder und Widgets ein:

   • Vor- und Nachname: ein textInput-Widget, das Strings akzeptiert.
   • Geburtsdatum: Ein dateTimePicker-Widget, das nur Datumsangaben akzeptiert.
   • Kontakttyp: ein selectionInput-Widget mit Optionsfeldern, über das Nutzer einen einzelnen Stringwert (entweder Personal oder Work) auswählen und senden können.
   • Schaltfläche Überprüfen und senden: ein buttonList-Array mit dem button-Widget, auf das der Nutzer klickt, um die eingegebenen Werte zu senden.

4. Die Google Chat App ruft openConfirmationDialog auf, um die vom Nutzer eingegebenen Werte zu verarbeiten, und zeigt die Werte auf einer Bestätigungskarte an.

5. Der Nutzer prüft die Bestätigungskarte und klickt auf den Button Senden, um submitForm aufzurufen und die Kontaktdaten zu bestätigen.

6. Die Google Chat App sendet eine private Nachricht, die die Einreichung bestätigt.

Umgebung vorbereiten

In diesem Abschnitt wird beschrieben, wie Sie ein Google Cloud-Projekt für die Chat-App konfigurieren.

Cloud-Projekt in der Google API Console öffnen

Öffnen Sie das Cloud-Projekt, das Sie für dieses Beispiel verwenden möchten, falls es noch nicht geöffnet ist:

1. Rufen Sie in der Google API Console die Seite Projekt auswählen auf.

   Cloud-Projekt auswählen

2. Wählen Sie das Google Cloud-Projekt aus, das Sie verwenden möchten. Klicken Sie alternativ auf Projekt erstellen und folgen Sie der Anleitung auf dem Bildschirm. Wenn Sie ein Google Cloud-Projekt erstellen, müssen Sie möglicherweise die Abrechnung für das Projekt aktivieren.

Authentifizierung und Autorisierung einrichten

Für Google Chat-Apps müssen Sie einen OAuth-Zustimmungsbildschirm konfigurieren, damit Nutzer Ihre App in Google Workspace-Anwendungen, einschließlich Google Chat, autorisieren können.

In dieser Anleitung stellen Sie eine Chat-App bereit, die nur für Tests und die interne Verwendung bestimmt ist. Daher ist es in Ordnung, Platzhalterinformationen für den Einwilligungsbildschirm zu verwenden. Bevor Sie die Chat-App veröffentlichen, müssen Sie alle Platzhalterinformationen durch echte Informationen ersetzen.

1. Rufen Sie in der Google API Console das Menü menu > Google Auth-Plattform > Branding auf.

   Zum Branding

2. Wenn Sie die Google Auth-Plattform bereits konfiguriert haben, können Sie die folgenden Einstellungen für den OAuth-Zustimmungsbildschirm unter Branding, Zielgruppe und Datenzugriff konfigurieren. Wenn Sie die Meldung Google Auth Platform noch nicht konfiguriert sehen, klicken Sie auf Jetzt starten:

   1. Geben Sie unter App-Informationen bei App-Name Contact Manager ein.
   2. Wählen Sie unter Nutzersupport-E‑Mail Ihre E‑Mail-Adresse oder eine geeignete Google-Gruppe aus.
   3. Klicken Sie auf Weiter.
   4. Wählen Sie unter Zielgruppe die Option Intern aus. Wenn Sie Intern nicht auswählen können, wählen Sie Extern aus.
   5. Klicken Sie auf Weiter.
   6. Geben Sie unter Kontaktdaten eine E-Mail-Adresse ein, unter der Sie über Änderungen an Ihrem Projekt benachrichtigt werden können.
   7. Klicken Sie auf Weiter.
   8. Sehen Sie sich unter Abschließen die Nutzerdatenrichtlinie für Google API-Dienste an. Wenn Sie damit einverstanden sind, wählen Sie Ich akzeptiere die Richtlinie zu Nutzerdaten für Google API-Dienste aus.
   9. Klicken Sie auf Weiter.
   10. Klicken Sie auf Erstellen.
   11. Wenn Sie Extern als Nutzertyp ausgewählt haben, fügen Sie Testnutzer hinzu:
       1. Klicken Sie auf Zielgruppe.
       2. Klicken Sie unter Testnutzer auf Nutzer hinzufügen.
       3. Geben Sie Ihre E‑Mail-Adresse und die aller anderen autorisierten Testnutzer ein und klicken Sie auf Speichern.

Chat-App erstellen und bereitstellen

Im folgenden Abschnitt erstellen und aktualisieren Sie ein Apps Script-Projekt mit dem Anwendungscode (Code.gs und appsscript.json) für Ihre Chat-App.

Optional können Sie sich das gesamte Projekt auf GitHub ansehen.

Auf GitHub ansehen

Hier eine Übersicht über die einzelnen Dateien:

Code.gs

Verarbeitet die gesamte App-Logik, einschließlich Nutzerinteraktionen (onMessage, onAppCommand, openInitialDialog, openConfirmationDialog und submitForm) und der Formulareingabe-Widgets, die auf Karten in Nachrichten und Dialogfeldern angezeigt werden.

Code.gs-Code ansehen

apps-script/chat/contact-form-app/Code.gs

Auf GitHub ansehen

/**
 * Copyright 2025 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} response that handles dialogs.
 */
function onMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [
      { buttonList: { buttons: [{
        text: "ADD CONTACT",
        onClick: { action: {
          function: "openInitialDialog",
          interaction: "OPEN_DIALOG"
        }}
      }]}}
    ]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [
    { textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    { dateTimePicker: {
      name: "contactBirthdate",
      label: "Birthdate",
      type: "DATE_ONLY"
    }},
    { selectionInput: {
      name: "contactType",
      label: "Contact type",
      type: "RADIO_BUTTON",
      items: [
        { text: "Work", value: "Work", selected: false },
        { text: "Personal", value: "Personal", selected: false }
      ]
    }},
    { buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: { function : "openConfirmationDialog" }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  const birthdate = event.commonEventObject.formInputs["contactBirthdate"].dateInput.msSinceEpoch;
  const type = event.commonEventObject.formInputs["contactType"].stringInputs.value[0];
  // Display the input values for confirmation
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [
    { textParagraph: { text: "Confirm contact information and submit:" }},
    { textParagraph: { text: "<b>Name:</b> " + name }},
    { textParagraph: { text: "<b>Birthday:</b> " + new Date(birthdate) }},
    { textParagraph: { text: "<b>Type:</b> " + type }},
    { buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [
          { key: "contactName", value: name },
          { key: "contactBirthdate", value: birthdate },
          { key: "contactType", value: type }
        ]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} close the dialog with a status in text notification or message.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: { action: "CLOSE_DIALOG"}}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "✅ " + event.commonEventObject.parameters["contactName"] + " has been added to your contacts."
  }}}}};
}

appsscript.json

Das Apps Script-Manifest, das das Apps Script-Projekt für die Chat-App definiert und konfiguriert.

appsscript.json-Code ansehen

apps-script/chat/contact-form-app/appsscript.json

Auf GitHub ansehen

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Contact Form app",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/contact-icon.png"
    },
    "chat": {}
  }
}

Apps Script-Projekt erstellen

So erstellen Sie ein Apps Script-Projekt aus den Dateien Code.gs und appsscript.json:

1. Rufen Sie Google Apps Script auf und klicken Sie auf Neues Projekt.

2. Geben Sie Ihrem Apps Script-Projekt einen Namen:

   1. Klicken Sie auf Unbenanntes Projekt.

   2. Geben Sie unter Projekttitel Contact Manager - Google Chat app ein.

   3. Klicken Sie auf Umbenennen.

3. Ersetzen Sie den Inhalt von Code.gs durch den oben stehenden Code.gs-Beispielcode.

4. Klicken Sie auf Projekteinstellungen und wählen Sie Manifestdatei „appsscript.json“ im Editor anzeigen aus.

5. Kehren Sie zum Editor zurück und ersetzen Sie den Inhalt von appsscript.json durch den oben stehenden Manifestcode für appsscript.json. Speichern Sie dann Ihr Projekt.

Wenn Sie in Zukunft bestimmte Google-APIs verwenden oder Ihre App veröffentlichen möchten, müssen Sie Ihr Cloud-Projekt mit Ihrem Apps Script-Projekt verknüpfen. Für diese Anleitung ist das nicht erforderlich. Weitere Informationen finden Sie in der Anleitung zu Google Cloud-Projekten.

Apps Script-Bereitstellung erstellen

Nachdem der gesamte Code vorhanden ist, stellen Sie das Apps Script-Projekt bereit. Sie verwenden die Bereitstellungs-ID, wenn Sie die Chat-App in Google Cloud konfigurieren.

1. Öffnen Sie in Apps Script das Projekt der Chat App.

   Zu Apps Script wechseln

2. Klicken Sie auf Bereitstellen > Neue Bereitstellung.

3. Wenn Add-on noch nicht ausgewählt ist, klicken Sie neben Typ auswählen auf die Bereitstellungstypen  und wählen Sie Add-on aus.

4. Geben Sie unter Beschreibung eine Beschreibung für diese Version ein, z. B. Test of Contact Manager.

5. Klicken Sie auf Bereitstellen. Apps Script meldet eine erfolgreiche Bereitstellung und stellt eine Bereitstellungs-ID bereit.

6. Klicken Sie auf content_copy Kopieren, um die Bereitstellungs-ID zu kopieren, und klicken Sie dann auf Fertig.

Chat-App in der Google API Console konfigurieren

In diesem Abschnitt wird beschrieben, wie Sie die Google Chat API in der Google API Console mit Informationen zu Ihrer Chat-App konfigurieren, einschließlich der ID der Bereitstellung, die Sie gerade aus Ihrem Apps Script-Projekt erstellt haben.

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

   Zur Chat API-Konfiguration

2. Geben Sie unter App-Name Contact Manager ein.

3. Geben Sie in Avatar-URL https://developers.google.com/chat/images/contact-icon.png ein.

4. Geben Sie unter Beschreibung Manage your personal and business contacts ein.

5. Klicken Sie auf den Ein/Aus-Button Interaktive Funktionen aktivieren, um die Option zu aktivieren.

6. Wählen Sie unter Funktionsweise die Option Gruppenbereichen und Gruppenunterhaltungen beitreten aus.

7. Wählen Sie unter Verbindungseinstellungen die Option Apps Script aus.

8. Fügen Sie unter Deployment-ID die Apps Script-Deployment-ID ein, die Sie im vorherigen Abschnitt beim Erstellen des Apps Script-Deployments kopiert haben.

9. Konfigurieren Sie unter Trigger die Funktionen, die auf Nutzerinteraktionen reagieren:

   • Geben Sie für den Trigger Nachricht onMessage ein.
   • Geben Sie für den Trigger App-Befehl den Wert onAppCommand ein.

10. Richten Sie unter Befehle die Slash-Befehle /about und /addContact ein:

    1. Klicken Sie auf Befehl hinzufügen, um den ersten Slash-Befehl einzurichten.
    2. Geben Sie unter Befehls-ID 1 ein.
    3. Geben Sie unter Beschreibung Learn how to use this Chat app to manage your contacts ein.
    4. Wählen Sie unter Befehlstyp die Option Slash command aus.
    5. Geben Sie unter Name des Slash-Befehls /about ein.
    6. Klicken Sie auf Fertig.
    7. Klicken Sie auf Befehl hinzufügen, um einen weiteren Slash-Befehl einzurichten.
    8. Geben Sie unter Befehls-ID 2 ein.
    9. Geben Sie unter Beschreibung Submit information about a contact ein.
    10. Wählen Sie unter Befehlstyp die Option Slash command aus.
    11. Geben Sie unter Name des Slash-Befehls /addContact ein.
    12. Wählen Sie Öffnet ein Dialogfeld aus.
    13. Klicken Sie auf Fertig.

11. Wählen Sie unter Sichtbarkeit das Kästchen Diese Chat-App bestimmten Personen und Gruppen in YOUR DOMAIN zur Verfügung stellen aus und geben Sie Ihre E‑Mail-Adresse ein.

12. Wählen Sie unter Logs die Option Fehler in Logging protokollieren aus.

13. Klicken Sie auf Speichern. Die Meldung „Die Konfiguration wurde gespeichert“ wird angezeigt.

Die Chat-App kann jetzt in Google Chat installiert und getestet werden.

Chat-App testen

So testen Sie Ihre Chat-App: Öffnen Sie einen Direktnachrichtenbereich mit der Chat-App und senden Sie eine Nachricht:

1. Öffnen Sie Google Chat mit dem Google Workspace-Konto, das Sie angegeben haben, als Sie sich als vertrauenswürdiger Tester hinzugefügt haben.

   Zu Google Chat wechseln

2. Klicken Sie auf add Neuer Chat.
3. Geben Sie im Feld Eine oder mehrere Personen hinzufügen den Namen Ihrer Chat-App ein.

4. Wählen Sie Ihre Chat-App in den Ergebnissen aus. Eine Direktnachricht wird geöffnet.

1. Geben Sie in der neuen Direktnachricht mit der Chat App /addContact ein und drücken Sie die Eingabetaste.

2. Geben Sie im Dialogfeld, das geöffnet wird, die Kontaktdaten ein:

   1. Geben Sie im Textfeld Vor- und Nachname einen Namen ein.
   2. Wählen Sie in der Datumsauswahl Geburtsdatum ein Datum aus.
   3. Wählen Sie unter Kontakttyp das Optionsfeld Geschäftlich oder Privat aus.

3. Klicken Sie auf Prüfen und senden.

4. Prüfen Sie im Bestätigungsdialog die von Ihnen eingegebenen Informationen und klicken Sie auf Senden. Die Chat-App antwortet mit einer Textnachricht, in der ✅ CONTACT NAME has been added to your contacts. steht.

5. Optional können Sie das Kontaktformular auch auf folgende Weise testen und senden:

   • Verwenden Sie den Slash-Befehl /about. Chat-App-Antworten mit einer Nachricht und einem Zubehör-Widget-Button mit dem Text Add a contact. Klicken Sie auf den Button, um ein Dialogfeld mit dem Kontaktformular zu öffnen.
   • Senden Sie eine Direktnachricht an die Chat App, ohne einen Slash-Befehl zu verwenden, z. B. Hello. Die Chat-App antwortet mit einem Text und einer Karte, die das Kontaktformular enthält.

Bereinigen

Damit Ihrem Google Cloud-Konto die in dieser Anleitung verwendeten Ressourcen nicht in Rechnung gestellt werden, empfehlen wir, das Cloud-Projekt zu löschen.

1. Wechseln Sie in der Google API Console zur Seite Ressourcen verwalten. Klicken Sie auf das Menü menu > IAM und Verwaltung > Ressourcen verwalten.

   Zum Ressourcenmanager

2. Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie auf Löschen delete.
3. Geben Sie im Dialogfeld die Projekt-ID ein und klicken Sie auf Beenden, um das Projekt zu löschen.

Weitere Informationen

• Auf Befehle reagieren
• Informationen von Google Chat-Nutzern erheben und verarbeiten
• Interaktive Dialogfelder öffnen
• Weitere Beispiele für Google Chat-Apps