Informationen von Google Chat-Nutzern erheben und verarbeiten

In diesem Leitfaden wird beschrieben, wie Google Chat-Apps Informationen von Nutzern erheben und verarbeiten können, indem sie Formulareingaben in cardbasierten Benutzeroberflächen einbinden.

In Google Chat werden Add-ons für Nutzer als Google Chat-Apps angezeigt. Weitere Informationen finden Sie unter Google Chat erweitern – Übersicht.

Chat-Apps fordern von Nutzern Informationen an, um Aktionen in oder außerhalb von Google Chat auszuführen. Das kann auf folgende Arten geschehen:

• Konfigurieren Sie die Einstellungen. So können Sie beispielsweise Nutzern erlauben, Benachrichtigungseinstellungen anzupassen oder die Chat-App für einen oder mehrere Gruppenbereiche zu konfigurieren und hinzuzufügen.
• Informationen in anderen Google Workspace-Anwendungen erstellen oder aktualisieren Sie können Nutzern beispielsweise erlauben, einen Google Kalender-Termin zu erstellen.
• Nutzern erlauben, auf Ressourcen in anderen Apps oder Webdiensten zuzugreifen und sie zu aktualisieren So können Nutzer beispielsweise mit einer Chat-App den Status eines Supporttickets direkt über einen Chatbereich aktualisieren.

Vorbereitung

Formulare mit Karten erstellen

Zum Erfassen von Informationen entwerfen Chat-Apps Formulare und deren Eingaben und bauen sie in Karten ein. Chat-Apps können die folgenden Chat-Oberflächen verwenden, um Nutzern Karten anzuzeigen:

• Chatnachrichten, die eine oder mehrere Karten enthalten.
• Dialogfelder: Karten, die in Nachrichten und auf Startseiten in einem neuen Fenster geöffnet werden.

In Chat-Apps können die Karten mit den folgenden Widgets erstellt werden:

• Formular-Eingabe-Widgets, die Informationen von Nutzern anfordern. Optional können Sie Validierungsregeln für Eingabe-Widgets hinzufügen, damit Nutzer Informationen korrekt eingeben und formatieren. In Chat-Apps können die folgenden Eingabe-Widgets für Formulare verwendet werden:

  • Textfelder (textInput) für freien Text oder Vorschläge.

  • Auswahleingaben (selectionInput) sind auswählbare UI-Elemente wie Kästchen, Optionsfelder und Drop-down-Menüs. Auswahleingabe-Widgets können auch Elemente aus Google Workspace-Daten (z. B. einem Chatbereich) oder einer dynamischen Datenquelle einfügen und vorschlagen. Weitere Informationen finden Sie im folgenden Abschnitt Mehrfachauswahlmenü hinzufügen.

  • Datumsauswahl (dateTimePicker) für Datums- und Uhrzeitangaben.

• Ein Schaltflächen-Widget, mit dem Nutzer Werte einreichen können, die sie auf der Karte eingegeben haben. Nachdem ein Nutzer auf die Schaltfläche geklickt hat, kann die Chat-App die empfangenen Informationen verarbeiten.

Im folgenden Beispiel werden auf einer Karte Kontaktdaten mithilfe einer Texteingabe, einer Datumsauswahl und einer Auswahleingabe erfasst:

Weitere Beispiele für interaktive Widgets, mit denen Sie Informationen erfassen können, finden Sie in der Google Chat API-Dokumentation unter Interaktive Karte oder Dialogfeld entwerfen.

Mehrfachauswahl-Menü hinzufügen

Wenn Sie Auswahlelemente anpassen oder Nutzern die Auswahl von Elementen aus einer dynamischen Datenquelle ermöglichen möchten, können Sie in Chat-Apps Menüs mit Mehrfachauswahl verwenden. Dies ist eine Art SelectionInput-Widget. Auf der folgenden Karte wird beispielsweise ein Mehrfachauswahlmenü angezeigt, in dem Nutzer dynamisch aus einer Liste von Kontakten auswählen können:

Sie können Elemente für ein Mehrfachauswahlmenü aus den folgenden Datenquellen einfügen:

• Google Workspace-Daten, einschließlich Nutzer oder Chatbereiche, in denen der Nutzer Mitglied ist. Das Menü enthält nur Elemente aus derselben Google Workspace-Organisation.
• Externe Datenquellen, z. B. eine relationale Datenbank. Mithilfe von Mehrfachauswahlmenüs können Sie Nutzern beispielsweise die Auswahl aus einer Liste von Leads aus einem CRM-System (Customer Relationship Management) erleichtern.

Elemente aus einer Google Workspace-Datenquelle einfügen

Wenn Sie Google Workspace-Datenquellen verwenden möchten, geben Sie das Feld platformDataSource im SelectionInput-Widget an. Im Gegensatz zu anderen Auswahleingabetypen können Sie SelectionItem-Objekte nicht ausschließen, da diese Auswahlelemente dynamisch aus Google Workspace abgerufen werden.

Der folgende Code zeigt ein Mehrfachauswahlmenü mit Google Workspace-Nutzern. Um Nutzer einzufügen, wird in der Auswahleingabe commonDataSource auf USER gesetzt:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

Der folgende Code zeigt ein Mehrfachauswahlmenü für Gruppenbereiche. Für die Befüllung von Bereichen wird in der Auswahleingabe das Feld hostAppDataSource angegeben. Im Menü für die Mehrfachauswahl wird außerdem defaultToCurrentSpace auf true gesetzt, wodurch der aktuelle Gruppenbereich die Standardauswahl im Menü wird:

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

Elemente aus einer externen Datenquelle einfügen

In Menüs mit Mehrfachauswahl können auch Elemente aus einer Drittanbieter- oder externen Datenquelle eingefügt werden. Wenn Sie eine externe Datenquelle verwenden möchten, geben Sie im SelectionInput-Widget das Feld externalDataSource an, das die Funktion enthält, mit der Elemente aus der Datenquelle abgefragt und zurückgegeben werden.

Um die Anzahl der Anfragen an eine externe Datenquelle zu reduzieren, können Sie Vorschläge einfügen, die im Mehrfachauswahlmenü angezeigt werden, bevor Nutzer etwas eingeben. Sie können beispielsweise die zuletzt gesuchten Kontakte für den Nutzer einblenden. Wenn Sie vorgeschlagene Elemente aus einer externen Datenquelle einfügen möchten, geben Sie statische SelectionItem-Objekte an.

Der folgende Code zeigt ein Mehrfachauswahlmenü, über das Elemente aus einer externen Datenquelle abgefragt und eingefügt werden:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "externalDataSource": { "function": "FUNCTION" },
    // Suggested items loaded by default.
    // The list is static here but it could be dynamic.
    "items": [FUNCTION]
  }
}

Ersetzen Sie FUNCTION durch die HTTP-URL oder den Namen der Apps Script-Funktion, die die externe Datenbank abfragt. Ein vollständiges Beispiel zum Zurückgeben vorgeschlagener Elemente finden Sie im Abschnitt Mehrfachauswahlelemente vorschlagen.

Daten von interaktiven Widgets empfangen

Jedes Mal, wenn Nutzer auf eine Schaltfläche klicken, wird die Aktion der Chat-App mit Informationen zur Interaktion ausgelöst. Im commonEventObject der Ereignisnutzlast enthält das formInputs-Objekt alle Werte, die der Nutzer eingibt.

Sie können die Werte aus dem Objekt commonEventObject.formInputs.WIDGET_NAME abrufen. Dabei ist WIDGET_NAME das name-Feld, das Sie für das Widget angegeben haben. Die Werte werden als bestimmter Datentyp für das Widget zurückgegeben.

Im Folgenden sehen Sie einen Teil eines Ereignisobjekts, in dem ein Nutzer Werte für jedes Widget eingegeben hat:

{
  "commonEventObject": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

Um die Daten zu empfangen, verarbeitet Ihre Chat-App das Ereignisobjekt, um die Werte abzurufen, die Nutzer in Widgets eingeben. In der folgenden Tabelle wird gezeigt, wie Sie den Wert für ein bestimmtes Formulareingabe-Widget abrufen. Für jedes Widget wird in der Tabelle der Datentyp angezeigt, den das Widget akzeptiert, wo der Wert im Ereignisobjekt gespeichert wird, und ein Beispielwert.

Nachdem die Chat-App Daten erhalten hat, kann sie Folgendes tun:

• Bei Karten mit einem Mehrfachauswahlmenü können Sie Elemente einfügen oder vorschlagen, je nachdem, was der Nutzer in das Menü eingibt.
• Übertragen Sie die Daten auf eine andere Karte, damit der Nutzer seine Informationen überprüfen oder mit dem nächsten Abschnitt des Formulars fortfahren kann.
• Antworten Sie dem Nutzer, um zu bestätigen, dass er das Formular erfolgreich ausgefüllt hat.

Mehrere Elemente auswählen

Wenn eine Karte ein Mehrfachauswahlmenü enthält, das Elemente aus einer externen Datenquelle einfügt, kann die Chat-App Vorschläge basierend auf dem zurückgeben, was Nutzer in das Menü eingeben. Wenn ein Nutzer beispielsweise Atl für ein Menü eingibt, in dem Städte in den USA angezeigt werden, kann Ihre Chat-App Atlanta automatisch vorschlagen, bevor der Nutzer fertig ist. Die Chat-App kann bis zu 100 Elemente vorschlagen.

Damit Elemente in einem Mehrfachauswahlmenü vorgeschlagen und dynamisch eingefügt werden können, muss das SelectionInput-Widget auf der Karte eine Funktion angeben, die die externe Datenquelle abfragt. Damit die Funktion Vorschläge zurückgeben kann, muss sie Folgendes tun:

1. Behandle ein Ereignisobjekt, das die Chat-App empfängt, wenn Nutzer etwas in das Menü eingeben.
2. Rufen Sie aus dem Ereignisobjekt den Wert ab, den der Nutzer eingibt, der im Feld event.commonEventObject.parameters["autocomplete_widget_query"] dargestellt wird.
3. Die Datenquelle mit dem Nutzereingabewert abfragen, um eine oder mehrere SelectionItems zu erhalten, die dem Nutzer vorgeschlagen werden sollen.
4. Gib vorgeschlagene Elemente zurück, indem du die Aktion RenderActions mit einem modifyCard-Objekt zurückgibst.

Das folgende Codebeispiel zeigt, wie eine Chat-App auf einer Karte dynamisch Elemente im Mehrfachauswahlmenü vorschlägt. Wenn ein Nutzer etwas in das Menü eingibt, wird über die Funktion oder den Endpunkt im Feld externalDataSource des Widgets eine externe Datenquelle abgefragt und es werden Elemente vorgeschlagen, die der Nutzer auswählen kann.

/**
 * Google Cloud Function that responds to events sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.selectionInput = function selectionInput(req, res) {
  if (req.method === 'GET' || !req.body.chat) {
    return res.send('Hello! This function is meant to be used ' +
        'in a Google Chat Space.');
  }
  // Stores the Google Chat event
  const chatEvent = req.body.chat;

  // Handle user interaction with multiselect.
  if(chatEvent.widgetUpdatedPayload) {
    return res.send(queryContacts(req.body));
  }
  // Replies with a card that contains the multiselect menu.
  return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "FUNCTION_URL" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}});
};

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a selection item in the menu.
 */
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

/**
* Responds to a Message trigger in Google Chat.
*
* @param {Object} event the event object from Google Chat
* @return {Object} Response from the Chat app.
*/
function onMessage(event) {
  // Replies with a card that contains the multiselect menu.
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "queryContacts" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact"3")]
        }
      }]}]}
    }]
  }}}}};
}

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the interactive event.
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
* Generate a suggested contact given an ID.
*
* @param {String} id The ID of the contact to return.
* @return {Object} The contact formatted as a selection item in the menu.
*/
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Daten auf eine andere Karte übertragen

Nachdem ein Nutzer Informationen von einer Karte gesendet hat, müssen Sie möglicherweise zusätzliche Karten zurücksenden, um eine der folgenden Aktionen auszuführen:

• Erstellen Sie separate Abschnitte, um Nutzern das Ausfüllen längerer Formulare zu erleichtern.
• Bieten Sie Nutzern die Möglichkeit, sich eine Vorschau der Informationen auf der ersten Karte anzusehen und zu bestätigen, damit sie ihre Antworten vor dem Senden prüfen können.
• Die restlichen Teile des Formulars werden dynamisch ausgefüllt. Wenn Sie Nutzer beispielsweise dazu auffordern möchten, einen Termin zu erstellen, könnte eine Chat-App eine erste Karte anzeigen, auf der der Grund für den Termin abgefragt wird, und dann eine weitere Karte mit verfügbaren Zeiten basierend auf dem Termintyp einblenden.

Um die Dateneingabe von der ursprünglichen Karte zu übertragen, können Sie das button-Widget mit actionParameters erstellen, das die name des Widgets und den vom Nutzer eingegebenen Wert enthält, wie im folgenden Beispiel gezeigt:

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "submitForm",
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

Dabei ist WIDGET_NAME die name des Widgets und USER_INPUT_VALUE die Eingabe des Nutzers. Bei einer Texteingabe, über die der Name einer Person erfasst wird, ist der Widget-Name beispielsweise contactName und ein Beispielwert ist Kai O.

Wenn ein Nutzer auf die Schaltfläche klickt, erhält Ihre Chat-App ein Ereignisobjekt, von dem Sie Daten empfangen können.

Auf eine Formulareinreichung reagieren

Nachdem die Chat-App die Daten aus einer Kartennachricht oder einem Kartendialog erhalten hat, antwortet sie entweder mit einer Empfangsbestätigung oder einem Fehler.

Im folgenden Beispiel sendet eine Chat-App eine SMS, um zu bestätigen, dass ein Formular, das über eine Kartennachricht gesendet wurde, erfolgreich empfangen wurde.

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  const chatMessage = chatEvent.messagePayload.message;

  // Handle message payloads in the event object
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(chatMessage, chatEvent.user));
  // Handle button clicks on the card
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openDialog":
            return res.send(openDialog());
        case "openNextCard":
            return res.send(openNextCard(req.body));
        case "submitForm":
            return res.send(submitForm(req.body));
    }
  }
};

/**
 * Submits information from a dialog or card message.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

/**
 * Sends private text message that confirms submission.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

Wenn Sie ein Dialogfeld verarbeiten und schließen möchten, geben Sie ein RenderActions-Objekt zurück, in dem angegeben ist, ob Sie eine Bestätigungsnachricht senden, die ursprüngliche Nachricht oder Karte aktualisieren oder das Dialogfeld einfach schließen möchten. Eine Anleitung finden Sie unter Dialogfeld schließen.

Fehlerbehebung

Wenn eine Google Chat-App oder Karte einen Fehler zurückgibt, wird in der Chat-Benutzeroberfläche die Meldung „Ein Fehler ist aufgetreten“ angezeigt. oder „Ihre Anfrage konnte nicht verarbeitet werden“ Manchmal wird in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt, aber die Chat-App oder -Karte führt zu einem unerwarteten Ergebnis. Beispielsweise wird möglicherweise keine Kartennachricht angezeigt.

Auch wenn in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt wird, sind beschreibende Fehlermeldungen und Protokolldaten verfügbar, die Ihnen bei der Fehlerbehebung helfen, wenn die Fehlerprotokollierung für Chat-Apps aktiviert ist. Informationen zum Ansehen, Entfernen und Beheben von Fehlern finden Sie unter Google Chat-Fehler beheben.