In diesem Leitfaden wird erläutert, wie Sie die
messages.create()
um eine der folgenden Aktionen auszuführen:
- Senden Sie Nachrichten, die Text, Karten und interaktive Widgets enthalten.
- Nachrichten privat an einen bestimmten Chat-Nutzer senden.
- Sie können eine Unterhaltung starten oder darauf antworten.
- Benennen Sie eine Nachricht, damit Sie sie in einer anderen Chat API angeben können -Anfragen.
<ph type="x-smartling-placeholder">
Neben der Methode messages.create()
können Chat-Apps
Nachrichten erstellen und senden, um auf Interaktionen von Nutzern zu antworten, z. B.
Willkommensnachricht, nachdem ein Nutzer die Chat-App einer
Leerzeichen. Beim Reagieren auf Interaktionen können Chat-Apps andere
Arten von Messaging-Funktionen wie interaktive Dialogfelder und Linkvorschau
Schnittstellen. Um einem Nutzer zu antworten, gibt die Chat App
die Nachricht synchron, ohne die Chat API aufzurufen. Weitere Informationen
wie Sie Nachrichten senden, um auf Interaktionen zu reagieren,
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 Methode messages.create()
mit
App-Authentifizierung
und Nutzerauthentifizierung.
In Google Chat wird der Absender der Nachricht unterschiedlich zugeordnet
je nach verwendetem Authentifizierungstyp.
Wenn Sie sich als Chat-App authentifizieren, die Chat-App die Nachricht sendet.
<ph type="x-smartling-placeholder">App
angezeigt.Wenn Sie sich als Nutzer authentifizieren, sendet die Chat-App die im Namen des Nutzers senden. In Chat wird auch die Chat-App an die Nachricht, indem der Name angezeigt wird.
<ph type="x-smartling-placeholder">Der Authentifizierungstyp bestimmt auch, welche Messaging-Funktionen und -Oberflächen die Sie in die Nachricht aufnehmen können. Bei der App-Authentifizierung Chat-Apps können Nachrichten senden, die RTF, kartenbasierten Oberflächen und interaktiven Widgets. Da Google Chat-Nutzer nur Text in ihren Nachrichten senden können, haben Sie folgende Möglichkeiten: nur Text enthalten, wenn Nachrichten mithilfe der Nutzerauthentifizierung erstellt werden. Weitere Informationen zur Nachrichtenfunktion die für die Chat API zur Verfügung stehen, finden Sie in der Nachrichten in Google Chat
In diesem Leitfaden wird erläutert, wie du beide Authentifizierungstypen zum Senden einer Nachricht verwendest mit der Chat-API.
Vorbereitung
Python
- Unternehmen Google Workspace-Konto mit Zugriff auf Google Chat:
- Richten Sie Ihre Umgebung ein:
<ph type="x-smartling-placeholder">
- </ph>
- Google Cloud-Projekt erstellen
- Konfigurieren Sie den OAuth-Zustimmungsbildschirm.
- Aktivieren und konfigurieren Sie die Google Chat API mit einem Namen, und eine Beschreibung der Chat App.
- Installieren Sie die Python Google API-Clientbibliothek
- Anmeldedaten für den Zugriff basierend auf der Authentifizierung in der Google Chat API erstellen
Anfrage:
<ph type="x-smartling-placeholder">
- </ph>
- So authentifizieren Sie sich als Chat-Nutzer:
OAuth-Client-ID erstellen
Anmeldedaten und speichern Sie die Anmeldedaten als JSON-Datei mit dem Namen
client_secrets.json
in Ihr lokales Verzeichnis. - So authentifizieren Sie sich als Chat-App:
Dienstkonto erstellen
Anmeldedaten und speichern Sie die Anmeldedaten als JSON-Datei mit dem Namen
credentials.json
- So authentifizieren Sie sich als Chat-Nutzer:
OAuth-Client-ID erstellen
Anmeldedaten und speichern Sie die Anmeldedaten als JSON-Datei mit dem Namen
- <ph type="x-smartling-placeholder"></ph> Wählen Sie einen Autorisierungsbereich aus, je nachdem, ob Sie sich als Nutzer oder als Chat-App.
- Ein Google Chat-Bereich, in dem der authentifizierte Nutzer oder Mitglied der Chat-App ist. So authentifizieren Sie sich als der Chat-App fügen Sie die Chat-App mit dem Gruppenbereich
SMS im Namen eines Nutzers senden
In diesem Abschnitt wird erläutert, wie Sie Nachrichten im Namen eines Nutzers mit Nutzerauthentifizierung Bei der Nutzerauthentifizierung darf der Inhalt der Nachricht nur Text enthalten und darf Nachrichtenfunktionen auslassen, die nur für Chat-Apps wie Kartenoberflächen und interaktive Widgets
Um die messages.create()
mithilfe der Nutzerauthentifizierung aufzurufen, müssen Sie die
folgende Felder in der Anfrage:
- Einen Autorisierungsbereich
die die Nutzerauthentifizierung für diese Methode unterstützt. Im folgenden Beispiel werden
den Bereich
chat.messages.create
. - Die Ressource
Space
, in der die Sie posten möchten. Der authentifizierte Nutzer muss Mitglied des Leerzeichen. - Die
Message
zu erstellende Ressource. Um den Inhalt der Nachricht zu definieren, müssen Sie den Parametertext
ein.
Optional können Sie Folgendes angeben:
- Das Feld
messageId
, mit dem Sie Geben Sie der Nachricht einen Namen, der in anderen API-Anfragen verwendet werden soll. - Die Felder
thread.threadKey
undmessageReplyOption
für Threads starten oder darauf antworten Wenn im Gruppenbereich Threading verwenden, wird dieses Feld ignoriert.
So senden Sie eine SMS im Namen eines Nutzers:
Python
- Erstellen Sie in Ihrem Arbeitsverzeichnis eine Datei mit dem Namen
chat_create_message_user.py
Fügen Sie den folgenden Code in
chat_create_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', # Optional. Sets custom ID for the message to use in other requests. messageId='client-myfirstusermessage', # The text message to create. body={ 'text': '👋 🌎Hello world! Text messages can contain things like:\n\n' + '* Hyperlinks 🔗\n' + '* Emojis 😄🎉\n' + '* Mentions of other Chat users `@` \n\n' 'For details, see the <https://developers.google.com/workspace/chat/format-messages|Chat API developer documentation>.' } ).execute() # Prints details about the created message. print(result) if __name__ == '__main__': main()
Ersetzen Sie
SPACE
durch die ID aus dername
ein. Sie erhalten die ID durch Aufrufen derspaces.list()
-Methode oder aus der URL des Gruppenbereichs.Erstellen Sie das Beispiel in Ihrem Arbeitsverzeichnis und führen Sie es aus:
python3 chat_create_message_user.py
Wenn Sie dazu aufgefordert werden, öffnen Sie die URL, um den Chat-App basierend auf dem Bereich, den Sie in Ihrem
Die Chat-App erstellt die Nachricht und die authentifizierte
Der Nutzer postet die Nachricht im Gruppenbereich. In der Befehlszeile
Die Chat API gibt die Instanz des neuen
Message
.
Nachricht als Chat-App senden
In diesem Abschnitt wird erläutert, wie Sie Nachrichten senden, die Text, Karten und interaktive Zubehör-Widgets App-Authentifizierung.
Zum Aufrufen von messages.create()
mithilfe der App-Authentifizierung müssen Sie die Methode
folgende Felder in der Anfrage:
- Der Autorisierungsbereich
chat.bot
. - Die Ressource
Space
, in der die Sie posten möchten. Die Chat-App muss Mitglied des Gruppenbereichs. - Die
Message
zu erstellende Ressource. Um den Inhalt der Nachricht zu definieren, können Sie RTF (text
), eine oder mehrere Kartenschnittstellen (cardsV2
), oder beides.
Optional können Sie Folgendes angeben:
- Das einzuschließende Feld
accessoryWidgets
interaktiven Schaltflächen unten in der Nachricht. - Das Feld
privateMessageViewer
für Sendet die Nachricht privat an einen bestimmten Nutzer. - Das Feld
messageId
, mit dem Sie Geben Sie der Nachricht einen Namen, der in anderen API-Anfragen verwendet werden soll. - Die Felder
thread.threadKey
undmessageReplyOption
für Threads starten oder darauf antworten Wenn im Gruppenbereich Threading verwenden, wird dieses Feld ignoriert.
Die maximale Nachrichtengröße (inklusive Text oder Karten) beträgt 32.000 Byte. Wenn Sie eine Nachricht senden möchten, die diese Größe überschreitet, muss stattdessen mehrere Nachrichten senden.
So senden Sie eine in der Chat-App gepostete Nachricht mit folgendem Inhalt: Text, eine Karte und eine klickbare Schaltfläche unten in der Nachricht, führen Sie die folgenden Schritte aus:
Python
- Erstellen Sie in Ihrem Arbeitsverzeichnis eine Datei mit dem Namen
chat_create_message_app.py
Fügen Sie den folgenden Code in
chat_create_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) # Specify the Chat space where the message is posted. Obtain the ID # from the resource name, or from the space's URL. SPACE = 'spaces/SPACE' # Create a Chat message. result = chat.spaces().messages().create( # The Chat space. parent=SPACE, # Optional. Sets custom ID for the message to use in other requests. messageId='client-myfirstappmessage', # The message to create with text, a card, and a button at the # bottom of the message. body= { 'text': '👋 🌎Hello world! I created this message by calling the Chat API\'s `messages.create()` method.', 'cardsV2': [{ 'cardId': 'myCardId', 'card': { 'header': { 'title': 'About this message', 'imageUrl': 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg', 'imageType': 'CIRCLE' }, "sections": [ { "header": "Contents", "widgets": [ { "textParagraph": { "text": "🔡 <b>Text</b> which can include hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️." }}, { "textParagraph": { "text": "🖼️ A <b>card</b> to display visual elements and request information such as text 🔤, dates and times 📅, and selections ☑️." }}, { "textParagraph": { "text": "👉🔘 An <b>accessory widget</b> which adds a button to the bottom of a message." }}, ] }, { "header": "What's next", "collapsible": True, "widgets": [ { "textParagraph": { "text": "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>." }}, { "textParagraph": { "text": "🔄 <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/patch'>Update</a> or ❌ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/delete'>delete</a> the message." }}, { "textParagraph": { "text": '💡 <b>Pro tip</b>: To specify the message in other API requests, use its custom name: <i>' + SPACE + '/messages/client-myfirstappmessage</i>.' }} ] } ]} }], "accessoryWidgets": [ { "buttonList": { "buttons": [ { "text": "View documentation", "altText": "Opens a new browser tab and navigates to the Google Chat developer documentation website.", "icon": { "material_icon": { "name": "link" } }, "onClick": { "openLink": { "url": "https://developers.google.com/workspace/chat/create-messages" } } } ] } } ] } ).execute() print(result)
Ersetzen Sie
SPACE
durch die ID aus dername
ein. Sie erhalten die ID durch Aufrufen derspaces.list()
-Methode oder aus der URL des Gruppenbereichs.Erstellen Sie das Beispiel in Ihrem Arbeitsverzeichnis und führen Sie es aus:
python3 chat_create_message_app.py
Die Chat-App erstellt und postet die Nachricht im
Leerzeichen. In der Befehlszeile gibt die Chat API den Fehlercode
Instanz des neuen
Message
.
Interaktive Widgets am Ende einer Nachricht hinzufügen
In dem Codebeispiel aus dem vorherigen Abschnitt Bei der Chat-App-Nachricht wird im Bereich in der Meldung angezeigt wird – das sogenannte Zubehör-Widget. Zubehör-Widgets werden nach Text oder Karten in einer Nachricht angezeigt. Mit diesen Widgets können Sie die Nutzer auf verschiedene Arten mit Ihrer Botschaft interagieren können, z. B.:
- 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[]
im Text Ihrer Anfrage und geben Sie ein oder mehrere Widgets an, die Sie
enthalten sein sollen.
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.
<ph type="x-smartling-placeholder">![Zubehör-Widget.](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/message-accessory-widgets-reference.png?authuser=19&hl=de)
Hier sehen Sie den Text der Anfrage, mit der eine Textnachricht mit
zwei Zubehörtasten. Wenn Nutzende auf eine Schaltfläche klicken, wird die entsprechende
(z. B. doUpvote
) die Interaktion 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",
}
}
}
]
}
}
]
Nachricht privat senden
Chat-Apps können private Nachrichten senden, damit die Die Nachricht ist nur für einen bestimmten Nutzer im Gruppenbereich sichtbar. Wenn ein die Chat-App eine private Nachricht sendet, zeigt ein Label, 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 Folgendes an:
privateMessageViewer
im Text Ihrer Anfrage. Um den Nutzer anzugeben, setzen Sie den Wert auf
User
-Ressource, die
für den Chat-Nutzer steht. Sie können auch die
name
des
User
, wie im folgenden Beispiel gezeigt:
{
"text": "Hello private world!",
"privateMessageViewer": {
"name": "users/USER_ID"
}
}
USER_ID
ersetzen
mit einer eindeutigen 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:
Threads starten oder antworten
Für Gruppenbereiche mit Threads: können Sie festlegen, ob mit einer neuen Nachricht ein Thread gestartet oder auf einen vorhandenen Thread.
Standardmäßig wird bei Nachrichten, die Sie mit der Chat API erstellen, ein neuer Diskussions-Thread. Damit Sie die Konversation leichter identifizieren und später darauf antworten können, können Sie ein Thread-Schlüssel in Ihrer Anfrage:
- Geben Sie im Text Ihrer Anfrage
thread.threadKey
ein. - Abfrageparameter angeben
messageReplyOption
um festzustellen, was passiert, falls der Schlüssel bereits vorhanden ist.
So erstellen Sie eine Antwort auf eine vorhandene Unterhaltung:
- Fügen Sie in den Anfragetext das Feld
thread
ein. Wenn festgelegt, können Sie geben Sie diethreadKey
die Sie erstellt haben. Andernfalls müssen Sie die Methodename
des Threads. - Geben Sie den Abfrageparameter
messageReplyOption
an.
Die folgende JSON-Datei zeigt ein Beispiel für den Anfragetext für eine Textnachricht, die
einen Thread mit dem Schlüssel helloWorldThread
startet oder antwortet:
{
'thread': {
'threadKey': 'helloWorldThread',
},
'text': '👋 🌎Hello world!'
}
Nachrichten benennen
Sie können eine Nachricht benennen, um eine Nachricht in zukünftigen API-Aufrufen abzurufen oder anzugeben.
indem Sie das Feld messageId
in Ihrer messages.create()
-Anfrage festlegen.
Durch einen Namen können Sie die Nachricht angeben, ohne den
vom System zugewiesene ID aus dem Ressourcennamen der Nachricht (dargestellt in der
name
Feld.
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
die vom System zugewiesene ID oder den benutzerdefinierten Namen, den Sie beim Erstellen des
angezeigt.
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 verwenden.
- Ist innerhalb eines Gruppenbereichs eindeutig. Eine Chat-App kann die dieselbe benutzerdefinierte ID für unterschiedliche Nachrichten verwenden.
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
- Verwenden Sie den Card Builder, um JSON-Kartennachrichten für Chat-Apps entwerfen und als Vorschau ansehen
- Nachrichten 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