In diesem Leitfaden werden die verschiedenen Möglichkeiten erläutert, mit denen Google Chat-Apps Nachrichten senden können:
- Sie können Text- und Kartennachrichten in Echtzeit senden, indem Sie auf eine Nutzerinteraktion reagieren.
- Senden Sie Text- und Kartennachrichten asynchron, indem Sie die Methode
create
für die RessourceMessage
aufrufen. - Sie können eine Unterhaltung starten oder darauf antworten.
- Senden und benennen Sie eine Nachricht.
Die Ressource Message
steht für eine Textnachricht oder eine Kartennachricht in Google Chat. Sie können eine Nachricht in der Google Chat API mit create
, get
, update
oder delete
durch Aufrufen der entsprechenden Methoden abrufen. Weitere Informationen zu Text- und Kartennachrichten finden Sie unter Google Chat-Nachrichten.
Anstatt die Methode create
für die Ressource Message
der Google Chat API aufzurufen, um eine Text- oder Kartennachricht asynchron zu senden, können Google Chat-Anwendungen auch Nachrichten erstellen, um in Echtzeit auf Nutzerinteraktionen zu reagieren. Antworten auf Nutzerinteraktionen erfordern keine Authentifizierung und unterstützen andere Arten von Nachrichten, einschließlich interaktiver Dialogfelder und Linkvorschauen. Weitere Informationen finden Sie unter Interaktionen mit der Google Chat-App empfangen und beantworten.
Voraussetzungen
Node.js
- Ein Google Workspace-Konto mit Zugriff auf Google Chat.
- Eine veröffentlichte Chat-App. Folgen Sie dieser quickstart, um eine Chat-App zu erstellen.
- Autorisierung, die für die Chat-Anwendung zum Senden asynchroner Nachrichten konfiguriert ist. Zum Senden von Nachrichten in Echtzeit ist keine Autorisierungskonfiguration erforderlich.
- Das Senden einer Textnachricht unterstützt die beiden folgenden Autorisierungsmethoden:
- Nutzerauthentifizierung mit dem Autorisierungsbereich
chat.messages.create
oderchat.messages
. - App-Authentifizierung mit dem Autorisierungsbereich
chat.bot
.
- Nutzerauthentifizierung mit dem Autorisierungsbereich
- Zum Senden einer Kartennachricht ist eine App-Authentifizierung mit dem Autorisierungsbereich
chat.bot
erforderlich.
- Das Senden einer Textnachricht unterstützt die beiden folgenden Autorisierungsmethoden:
Python
- Python 3.6 oder höher
- Das Paketverwaltungstool pip
Die neuesten Google-Clientbibliotheken für Python Führen Sie den folgenden Befehl in der Befehlszeile aus, um sie zu installieren oder zu aktualisieren:
pip3 install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib oauth2client
Eine veröffentlichte Chat-App. Informationen zum Erstellen und Veröffentlichen einer Chat-App finden Sie unter Google Chat-App erstellen.
Autorisierung, die für die Chat-Anwendung zum Senden asynchroner Nachrichten konfiguriert ist. Zum Senden von Nachrichten in Echtzeit ist keine Autorisierungskonfiguration erforderlich.
- Das Senden einer Textnachricht unterstützt die beiden folgenden Autorisierungsmethoden:
- Nutzerauthentifizierung mit dem Autorisierungsbereich
chat.messages.create
oderchat.messages
. - App-Authentifizierung mit dem Autorisierungsbereich
chat.bot
.
- Nutzerauthentifizierung mit dem Autorisierungsbereich
- Zum Senden einer Kartennachricht ist eine App-Authentifizierung mit dem Autorisierungsbereich
chat.bot
erforderlich.
- Das Senden einer Textnachricht unterstützt die beiden folgenden Autorisierungsmethoden:
Apps Script
- Ein Google Workspace-Konto mit Zugriff auf Google Chat.
- Eine veröffentlichte Chat-App. Folgen Sie dieser quickstart, um eine Chat-App zu erstellen.
SMS senden
In diesem Abschnitt werden die beiden folgenden Möglichkeiten zum Senden von SMS beschrieben:
- Sie können eine Textnachricht in Echtzeit senden, 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-Anwendung eine Textnachricht, sobald sie einem Gruppenbereich hinzugefügt wird. Weitere Informationen zu den Best Practices für das Onboarding von Nutzern finden Sie unter Nutzer und Gruppenbereiche durch hilfreiches Onboarding unterstützen.
Zum Senden einer SMS, wenn ein Nutzer Ihre Chat-App einem Gruppenbereich hinzufügt, reagiert die Chat-App auf ein ADDED_TO_SPACE
-Interaktionsereignis. Verwenden Sie den folgenden Code, um auf ADDED_TO_SPACE
-Interaktionsereignisse mit einer Textnachricht zu antworten:
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`.'
}
}
Das Codebeispiel gibt die folgende Textnachricht zurück:
SMS asynchron senden
Im folgenden Abschnitt wird erläutert, wie eine SMS asynchron mit der App- und Nutzerauthentifizierung gesendet wird.
Um eine SMS zu senden, übergeben Sie in Ihrer Anfrage Folgendes:
- Geben Sie bei der App-Authentifizierung den Autorisierungsbereich
chat.bot
an. Geben Sie bei der Nutzerauthentifizierung den Autorisierungsbereichchat.messages.create
an. - Rufen Sie die Methode
create
für die RessourceMessage
auf.
SMS mit App-Authentifizierung senden
So senden Sie eine SMS mit der 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 httplib2 import Http from oauth2client.service_account import ServiceAccountCredentials from apiclient.discovery import build # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name( 'credentials.json', SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http())) # 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 den Namen eines Gruppenbereichs, den Sie in der Chat API mit der Methodespaces.list()
oder aus der URL eines Gruppenbereichs abrufen können.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
zurück, die Details zur gesendeten Nachricht enthält.
SMS mit Nutzerauthentifizierung senden
So senden Sie eine SMS 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 membership. print(result) if __name__ == '__main__': main()
Ersetzen Sie im Code
SPACE
durch den Namen des Gruppenbereichs. Diesen finden Sie in der Chat API mit der Methodespaces.list()
oder aus der 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
zurück, die Details zur gesendeten Nachricht enthält.
Kartennachrichten senden
In diesem Abschnitt werden zwei Möglichkeiten zum Senden von Kartennachrichten beschrieben:
- Du kannst eine Kartennachricht in Echtzeit senden, indem du auf eine Nutzerinteraktion reagierst.
- Sie können eine Kartennachricht senden, indem Sie die Google Chat API asynchron aufrufen.
Kartennachricht in Echtzeit senden
Chat-Apps können Kartennachrichten erstellen, um auf eine Nutzerinteraktion zu reagieren, z. B. wenn ein Nutzer der Chat-App eine Nachricht sendet oder die Chat-App einem Gruppenbereich hinzufügt. Weitere Informationen zum Reagieren auf Nutzerinteraktionen finden Sie unter Interaktionsereignisse für Chat-Apps empfangen und beantworten.
In diesem Beispiel sendet ein Nutzer eine Nachricht an eine Chat-Anwendung und die Chat-Anwendung antwortet mit einer Kartennachricht, die den Namen und das Avatarbild des Nutzers enthält:
Node.js
Python
Apps Script
Eine Kartennachricht asynchron senden
Übergeben Sie zum Senden einer Kartennachricht Folgendes in Ihrer Anfrage:
- Geben Sie bei der App-Authentifizierung den Autorisierungsbereich
chat.bot
an. Sie können keine Kartennachricht mit Nutzerauthentifizierung senden. - Rufen Sie die Methode
create
für die RessourceMessage
auf.
Hier ein Beispiel für 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 httplib2 import Http from oauth2client.service_account import ServiceAccountCredentials from apiclient.discovery import build # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name( 'credentials.json', SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http())) # 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 den Namen eines Gruppenbereichs, den Sie in der Chat API mit der Methodespaces.list
oder aus der URL eines Gruppenbereichs abrufen können.Erstellen Sie das Beispiel in Ihrem Arbeitsverzeichnis und führen Sie es aus:
python3 chat_create_card_message.py
Unterhaltungsthreads in einer Nachricht starten oder beantworten
Wenn Sie einen Nachrichtenthread starten möchten, senden Sie eine Nachricht und lassen Sie thread.name
leer. Google Chat füllt dies beim Erstellen des Threads. Optional können Sie das Feld thread.threadKey
angeben, um den Namen des Threads anzupassen.
Zum Antworten auf einen Nachrichtenthread senden Sie eine Nachricht, die das Feld threadKey
oder name
des Threads angibt. Wenn der Thread von einer Person oder einer anderen Chat-App erstellt wurde, müssen Sie das Feld thread.name
verwenden.
Wenn keine passende Unterhaltung gefunden wird, können Sie mit dem Feld messageReplyOption
angeben, ob eine Nachricht einen neuen Thread starten oder nicht posten soll.
So starten oder beantworten Sie einen Thread mit dem Feld threadKey
, das als nameOfThread
definiert ist:
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 httplib2 import Http from oauth2client.service_account import ServiceAccountCredentials from apiclient.discovery import build # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name( 'credentials.json', SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http())) # 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 den Namen eines Gruppenbereichs, den Sie in der Chat API mit der Methodespaces.list
oder aus der URL eines Gruppenbereichs abrufen können.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
zurück, die Details zur gesendeten Nachricht enthält.
Nachrichten senden und benennen
In diesem Abschnitt wird erläutert, wie Sie eine Nachricht mit einem benutzerdefinierten Namen senden. Nachrichtennamen werden zum Abrufen, Aktualisieren oder Löschen von Nachrichten verwendet.
Durch die Zuweisung eines benutzerdefinierten Namens kann eine Chat-Anwendung die Nachricht auch zurückrufen, ohne die Nachricht name
aus dem Antworttext zu speichern, der beim Senden der Nachricht zurückgegeben wird.
Das Zuweisen eines benutzerdefinierten Namens ersetzt nicht das generierte Feld name
, also den Ressourcennamen der Nachricht. Stattdessen wird der benutzerdefinierte Name als Feld clientAssignedMessageId
festgelegt, auf das Sie bei der Verarbeitung späterer Vorgänge wie dem Aktualisieren oder Löschen der Nachricht verweisen können.
Für benutzerdefinierte Namen gelten die folgenden Anforderungen:
- Beginnen Sie mit
client-
. Beispielsweise istclient-custom-name
ein gültiger benutzerdefinierter Name,custom-name
jedoch nicht. - Er darf nur Kleinbuchstaben, Ziffern und Bindestriche enthalten.
- Er darf nicht länger als 63 Zeichen sein.
- Wenn Sie beim Senden einer Nachricht einen benutzerdefinierten Namen angeben, wird ein Fehler zurückgegeben. Andere Methoden wie
update
unddelete
funktionieren jedoch wie erwartet.
So senden und benennen Sie eine Nachricht:
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 httplib2 import Http from oauth2client.service_account import ServiceAccountCredentials from apiclient.discovery import build # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name( 'credentials.json', SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http())) # 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-custom-name', # The message to create. body={'text': 'Hello, world!'} ).execute() print(result)
Ersetzen Sie im Code
SPACE
durch den Namen eines Gruppenbereichs, den Sie in der Chat API mit der Methodespaces.list
oder aus der URL eines Gruppenbereichs abrufen können.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
zurück, die Details zur gesendeten Nachricht enthält.
Fehlerbehebung
Wenn eine Google Chat-App oder Google Chat-Karte einen Fehler zurückgibt, wird in der Chat-Oberfläche die Meldung „Ein Fehler ist aufgetreten“ oder „Ihre Anfrage konnte nicht verarbeitet werden“ angezeigt. Manchmal wird in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt, aber die Chat-App oder -Karte führt zu einem unerwarteten Ergebnis, z. B. kann es sein, dass keine Kartennachricht angezeigt wird.
Obwohl eine Fehlermeldung möglicherweise nicht in der Chat-Benutzeroberfläche angezeigt wird, sind beschreibende Fehlermeldungen und Protokolldaten verfügbar, mit denen Sie Fehler beheben können, wenn die Fehlerprotokollierung für Chat-Apps aktiviert ist. Informationen zum Aufrufen, Debuggen und Beheben von Fehlern finden Sie im Hilfeartikel Google Chat-Fehler beheben.
Weitere Informationen
- Nachricht formatieren
- Details zu einer Nachricht abrufen
- Nachrichten in einem Gruppenbereich auflisten
- Nachrichten aktualisieren
- Nachricht löschen
- Nutzer in Google Chat-Nachrichten identifizieren
- Nachrichten mit eingehenden Webhooks an Google Chat senden