In diesem Leitfaden werden die verschiedenen Möglichkeiten erläutert, mit denen Google Chat-Apps Nachrichten:
- Wenn du einem Nutzer antwortest, kannst du in Echtzeit Text- und Kartennachrichten senden Interaktion.
- Senden Sie Text- und Kartennachrichten asynchron, indem Sie die Methode
create
auf Die RessourceMessage
. - Sie können eine Unterhaltung starten oder darauf antworten.
- Nachrichten senden und benennen
Die
Message
-Ressource
steht für ein
Text
oder
Karte
in Google Chat. Sie können
create
, get
, update
oder delete
eine Nachricht in der Google Chat API durch den Aufruf von
entsprechenden Methoden. Weitere Informationen zu Text- und Kartennachrichten finden Sie unter
Nachrichten in Google Chat
Die maximale Nachrichtengröße (inklusive Text oder Karten) beträgt 32.000 Byte. Wenn eine Nachricht diese Größe überschreitet, zeigt Ihre Chat-App kann stattdessen mehrere Nachrichten senden.
Anstatt die Methode create
für die Ressource Message
von
die Google Chat API verwenden, um
SMS- oder Kartennachrichten asynchron zu senden,
Google Chat-Apps können auch Nachrichten erstellen, um auf Interaktionen von Nutzern in
in Echtzeit. Für Antworten auf Nutzerinteraktionen sind keine Authentifizierung und
unterstützen andere Arten von Mitteilungen, z. B. interaktive Dialogfelder und
Vorschauen ansehen. Weitere Informationen finden Sie unter
Interaktionen mit der Google Chat App empfangen und beantworten
Vorbereitung
Node.js
- Eine Google Chat App. So erstellen Sie eine Chat-App: einen HTTP-Dienst verwenden, führen Sie Schnellstart
- Autorisierung, die für die Chat-App zum Senden konfiguriert ist
asynchrone Nachrichten. Zum Senden ist keine Autorisierungskonfiguration erforderlich
Nachrichten in Echtzeit senden.
- Es wird ein
sms
unterstützt die beiden folgenden Autorisierungsmethoden:
- Nutzerauthentifizierung
mit der Autorisierung
chat.messages.create
oderchat.messages
Umfang. - App-Authentifizierung
mit dem Autorisierungsbereich
chat.bot
.
- Nutzerauthentifizierung
mit der Autorisierung
- Es wird ein
Kartennachricht
erfordert
App-Authentifizierung
mit dem Autorisierungsbereich
chat.bot
.
- Es wird ein
sms
unterstützt die beiden folgenden Autorisierungsmethoden:
Python
- Eine Google Chat App. So erstellen Sie eine Chat-App: einen HTTP-Dienst verwenden, führen Sie Schnellstart
- Autorisierung, die für die Chat-App zum Senden konfiguriert ist
asynchrone Nachrichten. Zum Senden ist keine Autorisierungskonfiguration erforderlich
Nachrichten in Echtzeit senden.
- Es wird ein
sms
unterstützt die beiden folgenden Autorisierungsmethoden:
- Nutzerauthentifizierung
mit der Autorisierung
chat.messages.create
oderchat.messages
Umfang. - App-Authentifizierung
mit dem Autorisierungsbereich
chat.bot
.
- Nutzerauthentifizierung
mit der Autorisierung
- Es wird ein
Kartennachricht
erfordert
App-Authentifizierung
mit dem Autorisierungsbereich
chat.bot
.
- Es wird ein
sms
unterstützt die beiden folgenden Autorisierungsmethoden:
Apps Script
- Eine Google Chat App. So erstellen Sie eine Chat-App: in Apps Script erstellen möchten, Schnellstart
- Autorisierung, die für die Chat-App zum Senden konfiguriert ist
asynchrone Nachrichten. Zum Senden ist keine Autorisierungskonfiguration erforderlich
Nachrichten in Echtzeit senden.
- Es wird ein
sms
unterstützt die beiden folgenden Autorisierungsmethoden:
- Nutzerauthentifizierung
mit der Autorisierung
chat.messages.create
oderchat.messages
Umfang. - App-Authentifizierung
mit dem Autorisierungsbereich
chat.bot
.
- Nutzerauthentifizierung
mit der Autorisierung
- Es wird ein
Kartennachricht
erfordert
App-Authentifizierung
mit dem Autorisierungsbereich
chat.bot
.
- Es wird ein
sms
unterstützt die beiden folgenden Autorisierungsmethoden:
SMS senden
In diesem Abschnitt wird beschrieben, wie Sie auf die beiden folgenden Arten Textnachrichten senden:
- Senden Sie eine Textnachricht in Echtzeit, indem Sie auf eine Nutzerinteraktion antworten.
- Senden Sie eine Textnachricht, indem Sie die Google Chat API asynchron aufrufen.
SMS in Echtzeit senden
In diesem Beispiel erstellt und sendet Ihre Chat-App eine Textnachricht wenn es einem Gruppenbereich hinzugefügt wird. Um mehr über Best Practices für finden Sie unter Nutzer und Gruppenbereiche mit hilfreichem Onboarding unterstützen
So senden Sie eine SMS, wenn ein Nutzer Ihre Chat-App hinzufügt:
in einem Gruppenbereich, Ihrer Chat-App
antwortet auf ADDED_TO_SPACE
interaction event (Interaktionsereignis). Um auf
ADDED_TO_SPACE
-Interaktionsereignisse. Verwenden Sie dazu den folgenden Code:
Node.js
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} event The event object from Chat API.
* @return {Object} Response from the Chat app. An onboarding message that
* introduces the app and helps people get started with it.
*/
exports.onMessage = function onMessage(req, res) {
if (req.method === 'GET' || !req.body.message) {
res.send(
'Hello! This function is meant to be used in a Google Chat space.');
}
// Send an onboarding message when added to a Chat space
if (req.body.type === 'ADDED_TO_SPACE') {
res.json({
'text': 'Hi, Cymbal at your service. I help you manage your calendar
from Google Chat. Take a look at your schedule today by typing
`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
learn what else I can do, type `/help`.'
});
}
};
Apps Script
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} event The event object from Chat API.
* @return {Object} Response from the Chat app. An onboarding message that
* introduces the app and helps people get started with it.
*/
function onAddToSpace(event) {
return {
'text': 'Hi, Cymbal at your service. I help you manage your calendar
from Google Chat. Take a look at your schedule today by typing
`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
what else I can do, type `/help`.'
}
}
Im Codebeispiel wird die folgende Textnachricht zurückgegeben:
SMS asynchron senden
Im folgenden Abschnitt wird erläutert, wie Sie eine Textnachricht asynchron mit App- und Nutzerauthentifizierung.
Um eine Textnachricht zu senden, übergeben Sie in Ihrer Anfrage Folgendes:
- Geben Sie für die App-Authentifizierung den Autorisierungsbereich
chat.bot
an. Mit Nutzerauthentifizierung: Geben Sie den Autorisierungsbereichchat.messages.create
an. - Rufen Sie die Methode
create
-Methode amMessage
-Ressource.
SMS mit App-Authentifizierung senden
So senden Sie eine Textnachricht mit App-Authentifizierung:
Python
- Erstellen Sie in Ihrem Arbeitsverzeichnis eine Datei mit dem Namen
chat_create_text_message_app.py
Fügen Sie den folgenden Code in
chat_create_text_message_app.py
ein:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Create a Chat message. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # The message to create. body={'text': 'Hello, world!'} ).execute() print(result)
Ersetzen Sie im Code
SPACE
durch einen Namen für den Gruppenbereich, der erhalten Sie in der Methodespaces.list()
in der Chat API oder über die URL eines Gruppenbereichs.Erstellen Sie das Beispiel in Ihrem Arbeitsverzeichnis und führen Sie es aus:
python3 chat_create_text_message_app.py
Die Chat API gibt eine Instanz von
Message
in der die gesendete Nachricht genau beschrieben wird.
SMS mit Nutzerauthentifizierung senden
So senden Sie eine Textnachricht mit Nutzerauthentifizierung:
Python
- Erstellen Sie in Ihrem Arbeitsverzeichnis eine Datei mit dem Namen
chat_create_text_message_user.py
Fügen Sie den folgenden Code in
chat_create_text_message_user.py
ein:import os.path from google.auth.transport.requests import Request from google.oauth2.credentials import Credentials from google_auth_oauthlib.flow import InstalledAppFlow from googleapiclient.discovery import build from googleapiclient.errors import HttpError # Define your app's authorization scopes. # When modifying these scopes, delete the file token.json, if it exists. SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"] def main(): ''' Authenticates with Chat API via user credentials, then creates a text message in a Chat space. ''' # Start with no credentials. creds = None # Authenticate with Google Workspace # and get user authorization. flow = InstalledAppFlow.from_client_secrets_file( 'client_secrets.json', SCOPES) creds = flow.run_local_server() # Build a service endpoint for Chat API. chat = build('chat', 'v1', credentials=creds) # Use the service endpoint to call Chat API. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # The message to create. body={'text': 'Hello, world!'} ).execute() # Prints details about the created message. print(result) if __name__ == '__main__': main()
Ersetzen Sie im Code
SPACE
durch einen Namen für den Gruppenbereich, der erhalten Sie in derspaces.list()
-Methode in der Chat API oder über die URL eines Gruppenbereichs.Erstellen Sie das Beispiel in Ihrem Arbeitsverzeichnis und führen Sie es aus:
python3 chat_create_text_message_user.py
Die Chat API gibt eine Instanz von
Message
in der die gesendete Nachricht genau beschrieben wird.
Kartennachrichten senden
In diesem Abschnitt wird beschrieben, wie Sie Kartennachrichten auf die beiden folgenden Arten senden:
- Du kannst in Echtzeit eine Kartennachricht senden, indem du auf eine Nutzerinteraktion antwortest.
- Senden Sie eine Kartennachricht, indem Sie die Google Chat API asynchron aufrufen.
Kartennachrichten in Echtzeit senden
Chat-Apps können Kartennachrichten erstellen, um einem Nutzer zu antworten Interaktion, z. B. wenn ein Nutzer der Chat-App eine oder die Chat App einem Gruppenbereich hinzufügen. Weitere Informationen zum Reagieren auf Nutzerinteraktionen finden Sie unter Empfangen und Antworten Interaktion mit der Chat-App Ereignisse.
In diesem Beispiel sendet ein Nutzer eine Nachricht an eine Chat-App. und die Chat-App antwortet mit einer Kartennachricht der den Namen und das Avatarbild des Nutzers anzeigt:
Node.js
Python
Apps Script
In diesem Beispiel wird eine Kartennachricht gesendet, JSON-Karte Sie können auch die Apps Script-Kartendienst
Kartennachricht asynchron senden
So senden Sie ein Kartennachricht, Übergeben Sie in Ihrer Anfrage Folgendes:
- Geben Sie für die App-Authentifizierung den Autorisierungsbereich
chat.bot
an. Sie können nicht eine Kartennachricht mit Nutzerauthentifizierung senden. - Rufen Sie die Methode
create
-Methode amMessage
-Ressource.
Das folgende Beispiel zeigt eine Kartennachricht:
So senden Sie eine Kartennachricht mit App-Authentifizierung:
Python
- Erstellen Sie in Ihrem Arbeitsverzeichnis eine Datei mit dem Namen
chat_create_card_message.py
Fügen Sie den folgenden Code in
chat_create_card_message.py
ein:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Create a Chat message. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # The message to create. body= { 'cardsV2': [{ 'cardId': 'createCardMessage', 'card': { 'header': { 'title': 'A card message!', 'subtitle': 'Created with the Chat API', 'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png', 'imageType': 'CIRCLE' }, 'sections': [ { 'widgets': [ { 'buttonList': { 'buttons': [ { 'text': 'Read the docs!', 'onClick': { 'openLink': { 'url': 'https://developers.google.com/chat' } } } ] } } ] } ] } }] } ).execute() print(result)
Ersetzen Sie im Code
SPACE
durch einen Namen für den Gruppenbereich, der erhalten Sie in der Methodespaces.list
in der Chat API oder über die URL eines Gruppenbereichs.Erstellen Sie das Beispiel in Ihrem Arbeitsverzeichnis und führen Sie es aus:
python3 chat_create_card_message.py
Nachrichten-Thread starten oder beantworten
Um eine Unterhaltung zu beginnen, sende eine Nachricht und verlasse sie
thread.name
leer; Google Chat füllt sie beim Erstellen des Threads mit Daten. Optional:
den Namen des Threads anpassen, den
thread.threadKey
ein.
Um auf einen Nachrichten-Thread zu antworten, senden Sie eine Nachricht, in der die
threadKey
- oder name
-Feld. Ob der Thread von einer Person erstellt wurde
Chat-App verwenden möchten, müssen Sie das Feld thread.name
verwenden.
Wenn kein übereinstimmender Thread gefunden wird, können Sie
Festlegen, ob eine Nachricht einen neuen Thread starten oder nicht gepostet werden soll
messageReplyOption
ein.
Wenn messageReplyOption
festgelegt ist, müssen Sie auch entweder thread.name
oder thread.threadKey
festlegen.
Hier erfahren Sie, wie Sie eine Unterhaltung starten oder darauf antworten, wenn das Feld threadKey
folgendermaßen definiert ist:
nameOfThread
:
Python
- Erstellen Sie in Ihrem Arbeitsverzeichnis eine Datei mit dem Namen
chat_create_message_thread.py
Fügen Sie den folgenden Code in
chat_create_message_thread.py
ein:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Create a Chat message. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # Whether to start a thread or reply to an existing one. # # Required when threading is enabled in a space unless starting a # thread. Ignored in other space types. Threading is enabled when # space.spaceThreadingState is THREADED_MESSAGES. # # REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD replies to an existing thread # if one exists, otherwise it starts a new one. messageReplyOption='REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD', # The message body. body={ # The message to create. 'text': 'Start or reply to another message in a thread!', # The thread to start or reply to. 'thread': { 'threadKey': 'nameOfThread' } } ).execute() print(result)
Ersetzen Sie im Code
SPACE
durch einen Namen für den Gruppenbereich, der erhalten Sie in der Methodespaces.list
in der Chat API oder über die URL eines Gruppenbereichs.Erstellen Sie das Beispiel in Ihrem Arbeitsverzeichnis und führen Sie es aus:
python3 chat_create_message_thread.py
Die Chat API gibt eine Instanz von
Message
in der die gesendete Nachricht genau beschrieben wird.
Nachrichten benennen
In diesem Abschnitt wird erläutert, wie Sie eine Nachricht benennen, indem Sie eine benutzerdefinierte ID für das
angezeigt. Sie können benutzerdefinierte IDs verwenden, um Nachrichten abzurufen, zu aktualisieren oder zu löschen. Benutzerdefinierte IDs
können Sie eine Nachricht angeben, ohne die vom System zugewiesene ID
Der Ressourcenname der Nachricht (dargestellt im Feld name
). Die Ressource
wird im Feld
Antworttext
wenn Sie die Mitteilung erstellen.
Wenn Sie beispielsweise eine Nachricht mit der Methode get()
abrufen möchten, verwenden Sie die Methode
Ressourcenname, um anzugeben, welche Nachricht abgerufen werden soll. Der Ressourcenname lautet
formatiert als spaces/{space}/messages/{message}
, wobei {message}
für
der vom System zugewiesenen ID. Wenn Sie der Nachricht einen Namen gegeben haben, können Sie
Wert von {message}
durch die benutzerdefinierte ID
Um eine Nachricht zu benennen, geben Sie eine benutzerdefinierte ID in der
messageId
wenn Sie die Mitteilung erstellen. Das Feld messageId
legt den Wert für die
clientAssignedMessageId
der Ressource Message
.
Sie können eine Nachricht nur benennen, wenn Sie sie erstellen. Sie können weder einen Namen eine benutzerdefinierte ID für vorhandene Nachrichten ändern. Die benutzerdefinierte ID muss folgende Anforderungen erfüllen Anforderungen:
- Beginnt mit
client-
.client-custom-name
ist beispielsweise ein gültiger benutzerdefinierter ID,custom-name
jedoch nicht. - Enthält bis zu 63 Zeichen und darf nur Kleinbuchstaben, Ziffern und Bindestriche.
- Ist innerhalb eines Gruppenbereichs eindeutig. Eine Chat-App kann die dieselbe benutzerdefinierte ID für unterschiedliche Nachrichten verwenden.
So senden Sie eine Nachricht mit einer benutzerdefinierten ID:
Python
- Erstellen Sie in Ihrem Arbeitsverzeichnis eine Datei mit dem Namen
chat_create_named_message.py
Fügen Sie den folgenden Code in
chat_create_named_message.py
ein:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Create a Chat message with a custom name. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # Custom name for the message used to facilitate later operations. messageId='client-NAME', # The message to create. body={'text': 'Hello, world!'} ).execute() print(result)
Ersetzen Sie im Code Folgendes:
SPACE
: Die ID des Gruppenbereichs, in dem Sie etwas speichern möchten veröffentlichen Sie die Nachricht. Diese finden Sie im Methodespaces.list
in der Chat API oder über die URL eines Gruppenbereichs.NAME
: Der benutzerdefinierte Name der Nachricht.
Erstellen Sie das Beispiel in Ihrem Arbeitsverzeichnis und führen Sie es aus:
python3 chat_create_named_message.py
Die Chat API gibt eine Instanz von
Message
Interaktive Widgets am Ende einer Nachricht hinzufügen
Optional können Sie Nachrichten mit Zubehör-Widgets anhängen. Zubehör-Widgets werden nach jedem Text oder jeder Karte in einer Nachricht angezeigt. Sie können diese Widgets, über die Nutzer auf vielfältige Weise mit Ihrer Botschaft interagieren können, z. B. Folgendes:
- Bewerten Sie die Genauigkeit oder Zufriedenheit einer Nachricht.
- Problem mit der Messages App oder der Chat App melden
- Öffnen Sie einen Link zu ähnlichen Inhalten, z. B. zur Dokumentation.
- Ähnliche Nachrichten aus der Chat App schließen oder zurückstellen für einen bestimmten Zeitraum.
Fügen Sie zum Hinzufügen von Zubehör-Widgets den
accessoryWidgets[]
-Objekt in der Nachricht und geben Sie mindestens eins an
AccessoryWidgets
die Sie einschließen möchten. Die Nachricht muss für alle im Gruppenbereich sichtbar sein
Sie können privaten Nachrichten keine Zubehör-Widgets hinzufügen.
In der folgenden Abbildung sehen Sie eine Chat-App, eine Textnachricht mit Zubehör-Widgets, damit Nutzer ihre Erfahrung bewerten können mit der Chat-App.
Das folgende Codebeispiel zeigt den JSON-Code für diese Nachricht. Wenn ein Nutzer auf
einer der Schaltflächen, löst die Interaktion die entsprechende Funktion aus (z. B.
doUpvote
), die die Bewertung verarbeitet.
"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",
}
}
}
]
}
}
]
Nachrichten privat senden
Chat-Apps können Text- und Kartennachrichten privat senden, damit das
Die Nachricht ist nur für einen Nutzer im Gruppenbereich sichtbar. So sendest du eine private Nachricht:
das Feld privateMessageViewer
in der Nachricht angeben. Nur
Chat-Apps können private Nachrichten senden. Um eine private Nachricht zu senden
müssen Sie die Anwendungsauthentifizierung verwenden.
Weitere Informationen finden Sie im Hilfeartikel Private Nachrichten an Google Chat senden Nutzer.
Fehlerbehebung
Wenn eine Google Chat-App oder card gibt einen Fehler zurück. Der Parameter In der Chatoberfläche wird die Meldung „Ein Fehler ist aufgetreten“ angezeigt. oder „Ihre Anfrage kann nicht verarbeitet werden.“ Manchmal kann die Chat-UI Es wird zwar keine Fehlermeldung angezeigt, aber die Chat-App oder die Karte zu einem unerwarteten Ergebnis führt. z. B. wird eine Kartennachricht angezeigt werden.
Auch wenn in der Chat-Benutzeroberfläche möglicherweise keine Fehlermeldung angezeigt wird, beschreibende Fehlermeldungen und Protokolldaten stehen zur Fehlerbehebung zur Verfügung. wenn die Fehlerprotokollierung für Chat-Apps aktiviert ist. Hilfe bei der Anzeige: Debugging und Beheben von Fehlern finden Sie unter Google Chat-Fehler beheben
Weitere Informationen
- Nachricht formatieren
- Details zu einer Nachricht abrufen
- Nachrichten in einem Gruppenbereich auflisten
- Nachricht aktualisieren
- Nachricht löschen
- Nutzer in Google Chat-Nachrichten identifizieren
- Nachrichten mit eingehenden Webhooks an Google Chat senden