Informationen von Google Chat-Nutzern erheben und verarbeiten

In diesem Leitfaden wird beschrieben, wie Google Chat-Apps Informationen von Nutzern erfassen und verarbeiten können, indem sie Formulareingaben in kartenbasierten Oberflächen erstellen.

Ein Dialogfeld mit verschiedenen Widgets.
Abbildung 1: Eine Chat-App, die ein Dialogfeld zum Erfassen von Kontaktinformationen öffnet.

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

  • Konfigurieren Sie die Einstellungen. So können Nutzer beispielsweise Benachrichtigungseinstellungen anpassen oder die Chat-App in einem oder mehreren Bereichen konfigurieren und hinzufügen.
  • Informationen in anderen Google Workspace-Anwendungen erstellen oder aktualisieren Lassen Sie Nutzer beispielsweise einen Google Kalender-Termin erstellen.
  • Nutzern erlauben, auf Ressourcen in anderen Apps oder Webservices zuzugreifen und diese zu aktualisieren. Mit einer Chat-App können Nutzer beispielsweise den Status eines Supporttickets direkt in einem Chat-Gruppenbereich aktualisieren.

Vorbereitung

HTTP

Ein Google Workspace-Add‑on, das Google Chat erweitert. HTTP-Schnellstart

Apps Script

Ein Google Workspace-Add‑on, das Google Chat erweitert. Wenn Sie eine erstellen möchten, folgen Sie der Apps Script-Kurzanleitung.

Formulare mit Karten erstellen

Zum Erfassen von Informationen werden in Chat-Apps Formulare und ihre Eingaben entworfen und in Karten eingebunden. Um Nutzern Karten zu präsentieren, können Chat-Apps die folgenden Chat-Schnittstellen verwenden:

  • Chatnachrichten, die eine oder mehrere Karten enthalten.
  • Dialoge sind Karten, die in einem neuen Fenster über Nachrichten und Startseiten geöffnet werden.

Chat-Apps können die Karten mit den folgenden Widgets erstellen:

  • Formulareingabe-Widgets, in denen Nutzer um Informationen gebeten werden. Optional können Sie Validierung für Formulareingabe-Widgets hinzufügen, damit Nutzer Informationen korrekt eingeben und formatieren. Chat-Apps können die folgenden Formulareingabe-Widgets verwenden:

    • Texteingaben (textInput) für Freiform- oder vorgeschlagenen Text.

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

    • Datums- und Uhrzeitauswahl (dateTimePicker) für Datums- und Zeiteingaben.

  • Ein Schaltflächen-Widget, damit Nutzer die in der Karte eingegebenen Werte senden können. Nachdem ein Nutzer auf die Schaltfläche geklickt hat, kann die Chat-App die empfangenen Informationen verarbeiten.

Im folgenden Beispiel werden mit einer Karte Kontaktdaten über eine Texteingabe, eine Auswahl für Datum und Uhrzeit und eine Auswahl eingegeben:

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 interaktiven Dialog gestalten.

Mehrfachauswahl-Menü hinzufügen

Wenn Sie Auswahlmöglichkeiten anpassen oder Nutzern erlauben möchten, Elemente aus einer dynamischen Datenquelle auszuwählen, können Chat-Apps Mehrfachauswahlmenüs verwenden. Diese sind eine Art von SelectionInput-Widget. Die folgende Karte enthält beispielsweise ein Menü mit Mehrfachauswahl, 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 abrufen:

  • Google Workspace-Daten, einschließlich Nutzer oder Chatbereiche, in denen der Nutzer Mitglied ist. Im Menü werden nur Elemente aus derselben Google Workspace-Organisation angezeigt.
  • Externe Datenquellen, z. B. eine relationale Datenbank. Sie können beispielsweise Mehrfachauswahlmenüs verwenden, damit ein Nutzer aus einer Liste von Vertriebs-Leads aus einem CRM-System (Customer Relationship Management) auswählen kann.

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 Auswahl-Eingabetypen lassen Sie SelectionItem-Objekte weg, da diese Auswahlmöglichkeiten dynamisch aus Google Workspace stammen.

Der folgende Code zeigt ein Menü mit Mehrfachauswahl für Google Workspace-Nutzer. Um Nutzer zu generieren, wird durch die Auswahl der Eingabe commonDataSource auf USER festgelegt:

JSON

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

Der folgende Code zeigt ein Mehrfachauswahlmenü mit Chatbereichen. Zum Ausfüllen von Leerzeichen wird das Feld hostAppDataSource im Auswahl-Input angegeben. Im Menü für die Mehrfachauswahl wird defaultToCurrentSpace auch auf true festgelegt. Dadurch wird der aktuelle Gruppenbereich zur Standardauswahl im Menü:

JSON

{
  "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 Auswahlmenü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 das Feld externalDataSource im SelectionInput-Widget 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 vorgeschlagene Elemente einfügen, die im Mehrfachauswahlmenü angezeigt werden, bevor Nutzer etwas eingeben. Sie können beispielsweise die zuletzt gesuchten Kontakte für den Nutzer anzeigen. Wenn Sie vorgeschlagene Artikel aus einer externen Datenquelle einfügen möchten, geben Sie statische SelectionItem-Objekte an.

Der folgende Code zeigt ein Menü mit Mehrfachauswahl, in dem Elemente aus einer externen Datenquelle abgefragt und eingefügt werden:

JSON

{
  "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, mit der die externe Datenbank abgefragt wird. Ein vollständiges Beispiel für das Zurückgeben vorgeschlagener Elemente finden Sie im Abschnitt Mehrfachauswahl-Elemente vorschlagen.

Daten von interaktiven Widgets empfangen

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, wobei WIDGET_NAME das Feld name ist, das Sie für das Widget angegeben haben. Die Werte werden als bestimmter Datentyp für das Widget zurückgegeben.

Das Folgende zeigt 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"]
    }}
  }}
}

Damit Ihre Chat-App die Daten empfangen kann, muss sie das Ereignisobjekt verarbeiten, um die Werte abzurufen, die Nutzer in Widgets eingeben. In der folgenden Tabelle sehen Sie, 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 ist, und ein Beispielwert.

Formulareingabe-Widget Art der Eingabedaten Eingabewert aus dem Ereignisobjekt Beispielwert
textInput stringInputs event.commonEventObject.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs So rufen Sie den ersten oder einzigen Wert ab: event.commonEventObject.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker, in dem nur Datumsangaben akzeptiert werden. dateInput event.commonEventObject.formInputs.contactBirthdate.dateInput.msSinceEpoch. 1000425600000

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

Mehrfachauswahl-Elemente vorschlagen

Wenn eine Karte ein Menü mit Mehrfachauswahl enthält, in dem Elemente aus einer externen Datenquelle eingefügt werden, kann die Chat-App Vorschläge zurückgeben, die auf dem basieren, 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 die Eingabe abgeschlossen hat. Die Chat-App kann bis zu 100 Artikel vorschlagen.

Damit Elemente in einem Mehrfachauswahlmenü vorgeschlagen und dynamisch eingefügt werden können, muss im SelectionInput-Widget auf der Karte eine Funktion zum Abfragen der externen Datenquelle angegeben werden. Damit vorgeschlagene Elemente zurückgegeben werden, muss die Funktion Folgendes ausführen:

  1. Verarbeiten Sie ein Ereignisobjekt, das die Chat-App empfängt, wenn Nutzer in das Menü eingeben.
  2. Rufen Sie aus dem Ereignisobjekt den Wert ab, den der Nutzer eingibt. Er wird im Feld event.commonEventObject.parameters["autocomplete_widget_query"] dargestellt.
  3. Fragen Sie die Datenquelle mit dem Nutzereingabewert ab, um einen oder mehrere SelectionItems abzurufen, die dem Nutzer vorgeschlagen werden sollen.
  4. Geben Sie vorgeschlagene Elemente zurück, indem Sie die Aktion RenderActions mit einem modifyCard-Objekt zurückgeben.

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

Node.js 

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

Ersetzen Sie FUNCTION_URL durch den HTTP-Endpunkt, mit dem die externe Datenquelle abgefragt wird.

Apps Script 

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

Daten auf eine andere Karte übertragen

Nachdem ein Nutzer Informationen von einer Karte gesendet hat, müssen Sie möglicherweise zusätzliche Karten zurückgeben, um Folgendes zu tun:

  • Nutzer können längere Formulare leichter ausfüllen, wenn Sie sie in verschiedene Abschnitte unterteilen.
  • Lassen Sie Nutzer Informationen aus der ersten Karte in der Vorschau ansehen und bestätigen, damit sie ihre Antworten vor dem Senden überprüfen können.
  • Füllen Sie die restlichen Teile des Formulars dynamisch aus. Wenn Nutzer beispielsweise aufgefordert werden sollen, einen Termin zu erstellen, kann eine Chat-App eine erste Karte anzeigen, in der der Grund für den Termin angegeben werden muss. Anschließend wird eine weitere Karte mit verfügbaren Zeiten basierend auf dem Termin typ angezeigt.

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:

Node.js

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "FUNCTION_URL", // Must be an `https` endpoint.
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

Apps Script 

{
  "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, in der der Name einer Person erfasst wird, ist der Name des Widgets beispielsweise contactName und ein Beispielwert Kai O.

Wenn ein Nutzer auf die Schaltfläche klickt, empfängt Ihre Chat-App ein Ereignisobjekt, aus dem Sie Daten abrufen können.

Auf eine Formulareinsendung reagieren

Nachdem die Chat-App die Daten aus einer Kartenmitteilung oder einem Dialogfeld erhalten hat, antwortet sie entweder mit einer Empfangsbestätigung oder gibt einen Fehler zurück.

Im folgenden Beispiel sendet eine Chat-App eine SMS, um zu bestätigen, dass sie ein über eine Kartenmitteilung gesendetes Formular erhalten hat.

Node.js

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

Apps Script 

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

Um ein Dialogfeld zu verarbeiten und zu schließen, geben Sie ein RenderActions-Objekt zurück, in dem angegeben wird, 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 kann nicht bearbeitet werden.“ Manchmal wird in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt, aber die Chat-App oder ‑Karte liefert ein unerwartetes Ergebnis, z. B. wird eine Kartennachricht nicht angezeigt.

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