In diesem Leitfaden wird erläutert, wie Sie mit der Methode create()
für die Ressource Message
der Google Chat API Folgendes tun können:
- Nachrichten senden, die Text, Karten und interaktive Widgets enthalten.
- Sie können Nachrichten privat an einen bestimmten Google Chat-Nutzer senden.
- Sie können eine Unterhaltung starten oder darauf antworten.
- Benennen Sie eine Nachricht, damit Sie sie in anderen Chat API-Anfragen angeben können.
Die maximale Nachrichtengröße (einschließlich Text oder Karten) beträgt 32.000 Byte. Um eine Nachricht zu senden, die diese Größe überschreitet, muss Ihre Chat-App stattdessen mehrere Nachrichten senden.
Chat-Apps können nicht nur die Chat API aufrufen, um Nachrichten zu erstellen, sondern auch Nachrichten erstellen und senden, um auf Nutzerinteraktionen zu antworten, z. B. eine Willkommensnachricht zu posten, nachdem ein Nutzer die Chat-App einem Gruppenbereich hinzugefügt hat. Wenn Sie auf Interaktionen reagieren, können Chat-Apps andere Arten von Nachrichtenfunktionen verwenden, z. B. interaktive Dialogfelder und Linkvorschauoberflächen. Wenn Sie einem Nutzer antworten, gibt die Chat-App die Nachricht synchron zurück, ohne die Chat API aufzurufen. Informationen zum Senden von Nachrichten, um auf Interaktionen zu antworten, finden Sie unter Interaktionen mit der Google Chat App empfangen und beantworten.
So werden in Google Chat mit der Chat API erstellte Nachrichten angezeigt und zugeordnet
Sie können die create()
-Methode mit App-Authentifizierung und Nutzerauthentifizierung aufrufen.
Chat ordnet den Absender der Nachricht je nach verwendeter Authentifizierungstyp unterschiedlich zu.
Wenn Sie sich als Chat-App authentifizieren, sendet die Chat-App die Nachricht.
Wenn Sie sich als Nutzer authentifizieren, sendet die Chat-App die Nachricht im Namen des Nutzers. Außerdem wird der Chat-App der Name der Nachricht zugeordnet.
Der Authentifizierungstyp bestimmt auch, welche Messaging-Funktionen und -Schnittstellen Sie in die Nachricht aufnehmen können. Mit der App-Authentifizierung können Chat-Apps Nachrichten senden, die Rich-Text, kartenbasierte Benutzeroberflächen und interaktive Widgets enthalten. Da Chat-Nutzer nur Textnachrichten senden können, können Sie nur dann Text eingeben, wenn Sie Nachrichten mit Nutzerauthentifizierung erstellen. Weitere Informationen zu den Messaging-Funktionen, die für die Chat API verfügbar sind, finden Sie unter Google Chat-Nachrichten – Übersicht.
In dieser Anleitung wird beschrieben, wie Sie mit beiden Authentifizierungstypen eine Nachricht mit der Chat API senden.
Vorbereitung
Node.js
- Ein Google Workspace-Konto für Unternehmen oder Organisationen mit Zugriff auf Google Chat.
- Richten Sie Ihre Umgebung ein:
- Google Cloud-Projekt erstellen
- Konfigurieren Sie den OAuth-Zustimmungsbildschirm.
- Aktivieren und konfigurieren Sie die Google Chat API mit einem Namen, einem Symbol und einer Beschreibung für Ihre Chat-App.
- Installieren Sie die Google Cloud-Clientbibliothek für Node.js.
- Erstellen Sie Anmeldedaten für den Zugriff, je nachdem, wie Sie sich in Ihrer Google Chat API-Anfrage authentifizieren möchten:
- Wenn Sie sich als Chat-Nutzer authentifizieren möchten, erstellen Sie Anmeldedaten für die OAuth-Client-ID und speichern Sie die Anmeldedaten als JSON-Datei mit dem Namen
client_secrets.json
in Ihrem lokalen Verzeichnis. - Wenn Sie sich als Chat-App authentifizieren möchten, erstellen Sie Anmeldedaten für das Dienstkonto und speichern Sie die Anmeldedaten als JSON-Datei mit dem Namen
credentials.json
.
- Wenn Sie sich als Chat-Nutzer authentifizieren möchten, erstellen Sie Anmeldedaten für die OAuth-Client-ID und speichern Sie die Anmeldedaten als JSON-Datei mit dem Namen
- Wählen Sie den Autorisierungsbereich aus, je nachdem, ob Sie sich als Nutzer oder über die Chat-App authentifizieren möchten.
- Ein Google Chat-Bereich, in dem der authentifizierte Nutzer oder die anrufende Chat-App Mitglied ist. Wenn Sie sich als Chat-App authentifizieren möchten, fügen Sie den Gruppenbereich die Chat-App hinzu.
Python
- Ein Google Workspace-Konto für Unternehmen oder Organisationen mit Zugriff auf Google Chat.
- Richten Sie Ihre Umgebung ein:
- Google Cloud-Projekt erstellen
- Konfigurieren Sie den OAuth-Zustimmungsbildschirm.
- Aktivieren und konfigurieren Sie die Google Chat API mit einem Namen, Symbol und einer Beschreibung für Ihre Chat-App.
- Installieren Sie die Cloud-Clientbibliothek für Python.
- Erstellen Sie Anmeldedaten für den Zugriff, je nachdem, wie Sie sich in Ihrer Google Chat API-Anfrage authentifizieren möchten:
- Wenn Sie sich als Chat-Nutzer authentifizieren möchten, erstellen Sie Anmeldedaten für die OAuth-Client-ID und speichern Sie die Anmeldedaten als JSON-Datei mit dem Namen
client_secrets.json
in Ihrem lokalen Verzeichnis. - Wenn Sie sich als Chat-App authentifizieren möchten, erstellen Sie Anmeldedaten für das Dienstkonto und speichern Sie die Anmeldedaten als JSON-Datei mit dem Namen
credentials.json
.
- Wenn Sie sich als Chat-Nutzer authentifizieren möchten, erstellen Sie Anmeldedaten für die OAuth-Client-ID und speichern Sie die Anmeldedaten als JSON-Datei mit dem Namen
- Wählen Sie den Autorisierungsbereich aus, je nachdem, ob Sie sich als Nutzer oder über die Chat-App authentifizieren möchten.
- Ein Google Chat-Bereich, in dem der authentifizierte Nutzer oder die anrufende Chat-App Mitglied ist. Fügen Sie die Chat-App dem Gruppenbereich hinzu, um sich als Chat-App zu authentifizieren.
Java
- Ein Google Workspace-Konto für Unternehmen oder Organisationen mit Zugriff auf Google Chat.
- Richten Sie Ihre Umgebung ein:
- Google Cloud-Projekt erstellen
- Konfigurieren Sie den OAuth-Zustimmungsbildschirm.
- Aktivieren und konfigurieren Sie die Google Chat API mit einem Namen, Symbol und einer Beschreibung für Ihre Chat-App.
- Installieren Sie die Java-Cloud-Clientbibliothek.
- Erstellen Sie Anmeldedaten für den Zugriff, je nachdem, wie Sie sich in Ihrer Google Chat API-Anfrage authentifizieren möchten:
- Wenn Sie sich als Chat-Nutzer authentifizieren möchten, erstellen Sie Anmeldedaten für die OAuth-Client-ID und speichern Sie die Anmeldedaten als JSON-Datei mit dem Namen
client_secrets.json
in Ihrem lokalen Verzeichnis. - Wenn Sie sich als Chat-App authentifizieren möchten, erstellen Sie Anmeldedaten für das Dienstkonto und speichern Sie die Anmeldedaten als JSON-Datei mit dem Namen
credentials.json
.
- Wenn Sie sich als Chat-Nutzer authentifizieren möchten, erstellen Sie Anmeldedaten für die OAuth-Client-ID und speichern Sie die Anmeldedaten als JSON-Datei mit dem Namen
- Wählen Sie den Autorisierungsbereich aus, je nachdem, ob Sie sich als Nutzer oder über die Chat-App authentifizieren möchten.
- Ein Google Chat-Bereich, in dem der authentifizierte Nutzer oder die aufrufende Chat-App Mitglied ist. Wenn Sie sich als Chat-App authentifizieren möchten, fügen Sie den Gruppenbereich die Chat-App hinzu.
Apps Script
- Ein Google Workspace-Konto für Unternehmen oder Organisationen mit Zugriff auf Google Chat.
- Richten Sie Ihre Umgebung ein:
- Google Cloud-Projekt erstellen
- Konfigurieren Sie den OAuth-Zustimmungsbildschirm.
- Aktivieren und konfigurieren Sie die Google Chat API mit einem Namen, Symbol und einer Beschreibung für Ihre Chat-App.
- Erstellen Sie ein eigenständiges Apps Script-Projekt und aktivieren Sie den erweiterten Chatdienst.
- In dieser Anleitung müssen Sie entweder die Nutzer- oder Anwendungsauthentifizierung verwenden. Erstellen Sie Anmeldedaten für ein Dienstkonto, um sich als Chat-App zu authentifizieren. Eine Anleitung dazu finden Sie unter Als Google Chat-App authentifizieren und autorisieren.
- Wählen Sie den Autorisierungsbereich aus, je nachdem, ob Sie sich als Nutzer oder über die Chat-App authentifizieren möchten.
- Ein Google Chat-Bereich, in dem der authentifizierte Nutzer oder die anrufende Chat-App Mitglied ist. Wenn Sie sich als Chat-App authentifizieren möchten, fügen Sie den Gruppenbereich die Chat-App hinzu.
Nachrichten als Chat-App senden
In diesem Abschnitt wird erläutert, wie Sie mithilfe der App-Authentifizierung Nachrichten senden, die Text, Karten und interaktive Zubehör-Widgets enthalten.
Wenn Sie die Methode CreateMessage()
mit App-Authentifizierung aufrufen möchten, müssen Sie in der Anfrage die folgenden Felder angeben:
- Der
chat.bot
-Autorisierungsbereich. - Die Ressource
Space
, in der Sie die Nachricht posten möchten. Die Chat-App muss Mitglied des Gruppenbereichs sein. - Die zu erstellende
Message
-Ressource. Sie können den Inhalt der Nachricht mithilfe von Rich Text (text
), einer oder mehreren Kartenoberflächen (cardsV2
) oder einer Kombination aus beiden definieren.
Optional können Sie Folgendes angeben:
- Das Feld
accessoryWidgets
, um interaktive Schaltflächen unten in der Nachricht einzufügen. - Das Feld
privateMessageViewer
, um die Nachricht privat an einen bestimmten Nutzer zu senden. - Das Feld
messageId
, mit dem du die Nachricht benennen kannst, um sie in anderen API-Anfragen zu verwenden. - Die Felder
thread.threadKey
undmessageReplyOption
, um eine Unterhaltung zu starten oder darauf zu antworten. Wenn im Gruppenbereich keine Unterhaltungen verwendet werden, wird dieses Feld ignoriert.
Im folgenden Codebeispiel wird gezeigt, wie eine Chat-App eine Nachricht senden kann, die als Chat-App gepostet wird und Text, eine Karte und eine anklickbare Schaltfläche unten in der Nachricht enthält:
Node.js
Python
Java
Apps Script
Ersetzen Sie zum Ausführen dieses Beispiels SPACE_NAME
durch die ID aus dem Feld name
des Leerzeichens. Sie können die ID durch Aufrufen der Methode ListSpaces()
oder aus der URL des Gruppenbereichs abrufen.
Interaktive Widgets unten in einer Nachricht hinzufügen
Im ersten Codebeispiel dieses Leitfadens wird in der Chat-App-Nachricht unten eine anklickbare Schaltfläche angezeigt, die als Zubehör-Widget bezeichnet wird. Widget für Zubehör wird nach Text oder Karten in einer Nachricht angezeigt. Mit diesen Widgets können Sie Nutzer auf verschiedene Arten dazu auffordern, mit Ihrer Mitteilung zu interagieren, z. B.:
- Bewerten Sie die Richtigkeit oder Zufriedenheit mit einer Nachricht.
- Problem mit der Messages App oder der Chat App melden
- Öffnen Sie einen Link zu ähnlichen Inhalten, z. B. zu einer Dokumentation.
- Ähnliche Nachrichten aus der Chat-App schließen oder für einen bestimmten Zeitraum zurückstellen.
Wenn Sie Zubehör-Widgets hinzufügen möchten, fügen Sie das Feld accessoryWidgets[]
in den Anfragetext ein und geben Sie ein oder mehrere Widgets an, die Sie einschließen möchten.
Das folgende Bild zeigt eine Chat-App, in der einer Nachricht zusätzliche Widgets angehängt werden, damit Nutzer ihre Erfahrungen mit der Chat-App bewerten können.
Im Folgenden sehen Sie den Text der Anfrage, mit der eine SMS mit zwei Zusatzschaltflächen erstellt wird. Wenn ein Nutzer auf eine Schaltfläche klickt, verarbeitet die entsprechende Funktion (z. B. doUpvote
) die Interaktion:
{
text: "Rate your experience with this Chat app.",
accessoryWidgets: [{ buttonList: { buttons: [{
icon: { material_icon: {
name: "thumb_up"
}},
color: { red: 0, blue: 255, green: 0 },
onClick: { action: {
function: "doUpvote"
}}
}, {
icon: { material_icon: {
name: "thumb_down"
}},
color: { red: 0, blue: 255, green: 0 },
onClick: { action: {
function: "doDownvote"
}}
}]}}]
}
Private Nachricht senden
Chat-Apps können Nachrichten privat senden, sodass die Nachricht nur für einen bestimmten Nutzer im Gruppenbereich sichtbar ist. Wenn eine Chat-App eine private Nachricht sendet, wird in der Nachricht ein Label angezeigt, das den Nutzer darüber informiert, dass die Nachricht nur für ihn sichtbar ist.
Wenn Sie eine Nachricht privat über die Chat API senden möchten, geben Sie das Feld privateMessageViewer
im Textkörper Ihrer Anfrage an. Wenn Sie den Nutzer angeben möchten, legen Sie den Wert auf die Ressource User
fest, die den Chat-Nutzer darstellt. Sie können auch das Feld name
der Ressource User
verwenden, wie im folgenden Beispiel gezeigt:
{
text: "Hello private world!",
privateMessageViewer: {
name: "users/USER_ID"
}
}
Wenn Sie dieses Beispiel verwenden möchten, ersetzen Sie USER_ID
durch eine eindeutige ID für den Nutzer, z. B. 12345678987654321
oder hao@cymbalgroup.com
. Weitere Informationen zum Angeben von Nutzern finden Sie unter Google Chat-Nutzer identifizieren und angeben.
Um eine Nachricht privat zu senden, müssen Sie in Ihrer Anfrage Folgendes weglassen:
SMS im Namen eines Nutzers senden
In diesem Abschnitt wird erläutert, wie Sie mithilfe der Nutzerauthentifizierung Nachrichten im Namen eines Nutzers senden. Bei der Nutzerauthentifizierung darf der Inhalt der Nachricht nur Text enthalten und es dürfen keine Nachrichtenfunktionen verwendet werden, die nur für Chat-Apps verfügbar sind, z. B. Kartenoberflächen und interaktive Widgets.
Wenn Sie die Methode CreateMessage()
mithilfe der Nutzerauthentifizierung aufrufen möchten, müssen Sie in der Anfrage die folgenden Felder angeben:
- Einen Autorisierungsbereich, der die Nutzerauthentifizierung für diese Methode unterstützt. Im folgenden Beispiel wird der Bereich
chat.messages.create
verwendet. - Die
Space
-Ressource, in der Sie die Nachricht posten möchten. Der authentifizierte Nutzer muss Mitglied des Gruppenbereichs sein. - Die zu erstellende
Message
-Ressource. Um den Inhalt der Nachricht zu definieren, müssen Sie das Feldtext
angeben.
Optional können Sie Folgendes angeben:
- Dem Feld
messageId
, mit dem Sie die Nachricht benennen können, die in anderen API-Anfragen verwendet werden soll - Die Felder
thread.threadKey
undmessageReplyOption
, um eine Unterhaltung zu starten oder darauf zu antworten. Wenn im Gruppenbereich keine Unterhaltungen verwendet werden, wird dieses Feld ignoriert.
Im folgenden Code wird gezeigt, wie eine Chat-App im Namen eines authentifizierten Nutzers eine Nachricht in einem bestimmten Gruppenbereich senden kann:
Node.js
Python
Java
Apps Script
Wenn Sie dieses Beispiel ausführen möchten, ersetzen Sie SPACE_NAME
durch die ID aus dem Feld name
des Gruppenbereichs. Sie erhalten die ID durch Aufrufen der Methode ListSpaces()
oder über die URL des Bereichs.
Unterhaltungen starten oder in Unterhaltungen antworten
Bei Gruppenbereichen, in denen Threads verwendet werden, können Sie festlegen, ob eine neue Nachricht einen Thread startet oder auf einen vorhandenen Thread antwortet.
Standardmäßig wird mit Nachrichten, die Sie über die Chat API erstellen, ein neuer Thread gestartet. Damit Sie den Thread später leichter identifizieren und darauf antworten können, können Sie in Ihrer Anfrage einen Threadschlüssel angeben:
- Geben Sie im Anfragetext das Feld
thread.threadKey
an. - Geben Sie den Abfrageparameter
messageReplyOption
an, um festzulegen, was passieren soll, wenn der Schlüssel bereits vorhanden ist.
So erstellen Sie eine Nachricht, die auf einen vorhandenen Thread antwortet:
- Geben Sie im Anfragetext das Feld
thread
an. Wenn diese Option festgelegt ist, können Sie den von Ihnen erstelltenthreadKey
angeben. Andernfalls müssen Sie diename
des Threads verwenden. - Geben Sie den Abfrageparameter
messageReplyOption
an.
Im folgenden Codebeispiel wird gezeigt, wie eine Chat-App im Namen eines authentifizierten Nutzers eine SMS senden kann, die einen bestimmten Thread startet oder auf einen bestimmten Thread antwortet, der durch den Schlüssel eines bestimmten Gruppenbereichs identifiziert wird:
Node.js
Python
Java
Apps Script
Ersetzen Sie zum Ausführen dieses Beispiels Folgendes:
THREAD_KEY
: ein vorhandener Thread-Schlüssel im Gruppenbereich oder ein eindeutiger Name für einen neuen Thread.SPACE_NAME
: die ID aus dem Feldname
des Gruppenbereichs. Sie erhalten die ID durch Aufrufen der MethodeListSpaces()
oder über die URL des Bereichs.
Nachrichten benennen
Wenn Sie eine Nachricht in zukünftigen API-Aufrufen abrufen oder angeben möchten, können Sie ihr einen Namen geben, indem Sie das Feld messageId
in Ihrer Anfrage festlegen.
Wenn Sie eine Nachricht benennen, können Sie sie angeben, ohne die vom System zugewiesene ID aus dem Ressourcennamen der Nachricht (im Feld name
dargestellt) speichern zu müssen.
Wenn Sie beispielsweise eine Nachricht mit der Methode get()
abrufen möchten, geben Sie mit dem Ressourcennamen an, welche Nachricht abgerufen werden soll. Der Ressourcenname hat das Format spaces/{space}/messages/{message}
, wobei {message}
für die vom System zugewiesene ID oder den benutzerdefinierten Namen steht, den Sie beim Erstellen der Nachricht festgelegt haben.
Um eine Nachricht zu benennen, geben Sie beim Erstellen der Nachricht eine benutzerdefinierte ID im Feld messageId
an. Das Feld messageId
legt den Wert für das Feld clientAssignedMessageId
der Ressource Message
fest.
Sie können eine Nachricht nur beim Erstellen benennen. Für vorhandene Nachrichten können Sie keine benutzerdefinierte ID benennen oder ändern. Die benutzerdefinierte ID muss die folgenden Anforderungen erfüllen:
- Beginnt mit
client-
. Beispiel:client-custom-name
ist eine gültige benutzerdefinierte ID,custom-name
jedoch nicht. - Enthält bis zu 63 Zeichen und nur Kleinbuchstaben, Ziffern und Bindestriche.
- Darf innerhalb eines Gruppenbereichs nur einmal vorkommen. Eine Chat-App kann nicht dieselbe benutzerdefinierte ID für verschiedene Nachrichten verwenden.
Der folgende Code zeigt ein Beispiel dafür, wie eine Chat-App im Namen eines authentifizierten Nutzers eine Textnachricht mit einer ID an einen bestimmten Bereich senden kann:
Node.js
Python
Java
Apps Script
Ersetzen Sie Folgendes, um dieses Beispiel auszuführen:
SPACE_NAME
: die ID aus dem Feldname
des Bereichs. Sie können die ID durch Aufrufen der MethodeListSpaces()
oder aus der URL des Gruppenbereichs abrufen.MESSAGE-ID
: ein Name für die Nachricht, der mitcustom-
beginnt. Der Name darf nicht mit dem Namen einer anderen Nachricht übereinstimmen, die in der Chat-App im angegebenen Gruppenbereich erstellt wurde.
Fehlerbehebung
Wenn eine Google Chat-App oder -Karte einen Fehler zurückgibt, wird in der Chat-Oberflä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 eine Kartennachricht möglicherweise nicht 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.
Weitere Informationen
- Mit dem Karten-Tool können Sie JSON-Kartennachrichten für Chat-Apps entwerfen und eine Vorschau anzeigen.
- Nachrichten formatieren
- Details zu einer Nachricht abrufen
- Nachrichten in einem Gruppenbereich auflisten
- Nachricht aktualisieren
- Nachricht löschen
- Nutzer in Google Chat-Nachrichten identifizieren
- Mithilfe von eingehenden Webhooks Nachrichten an Google Chat senden