Zusätzlich zu SMS können Chat-Apps Kartennachrichten in Gruppenbereichen und an Nutzer senden. Karten unterstützen ein definiertes Layout, interaktive UI-Elemente wie Schaltflächen und Rich Media wie Bilder.
Mit Kartennachrichten können Sie:
- Detaillierte Informationen präsentieren
- Informationen von Nutzern erfassen
- Nutzer als nächsten Schritt anleiten
In diesem Leitfaden wird beschrieben, wie Kartennachrichten synchron gesendet werden (eine Echtzeitantwort auf ein Chatereignis, z. B. das Empfangen einer Nachricht von einem Nutzer oder das Hinzufügen zu einem Gruppenbereich), und das asynchrone Senden einer Nachricht von der App an einen Gruppenbereich oder Nutzer ohne Aufforderung über die Chat REST API.
Voraussetzungen
Um die Kartennachrichten in dieser Anleitung zu senden, benötigen Sie Folgendes:
Node.js
- Ein Google Workspace-Konto mit Zugriff auf Google Chat.
- Eine Chat-App. Folgen Sie dieser Kurzanleitung, um eine Chat-App zu erstellen.
Hinweis: Die Codebeispiele in Node.js in diesem Leitfaden sind so geschrieben, dass sie als Google Cloud Functions-Funktion ausgeführt werden.
Python
- Ein Google Workspace-Konto mit Zugriff auf Google Chat.
- Eine Chat-App. Folgen Sie dieser Kurzanleitung, um eine Chat-App zu erstellen.
Hinweis: Die Python-Codebeispiele in diesem Leitfaden sind so geschrieben, dass sie als Google Cloud Functions-Funktion mit Python 3.9 ausgeführt werden.
Apps Script
- Ein Google Workspace-Konto mit Zugriff auf Google Chat.
- Eine Chat-App. Folgen Sie dieser Kurzanleitung, um eine Chat-App zu erstellen.
Aufbau einer Kartennachricht
Jede Karte, ob in Form eines Dialogs oder einer Nachricht, ist ein JSON-Objekt in der Ressource spaces.messages
in der Chat API.
Das JSON-Kartenobjekt besteht aus Folgendem:
- Ein Array mit dem Namen
cardsV2[]
, das ein oder mehrereCardWithId
-Objekte enthält. - Ein
cardId
, der zur Identifizierung der Karte verwendet wird und sich auf eine bestimmte Nachricht bezieht. (Karten in verschiedenen Nachrichten können dieselbe ID haben.) Ein
card
-Objekt, das Folgendes umfasst:- Ein
header
-Objekt, das Dinge wie einen Titel, einen Untertitel und ein Avatarbild angibt. - Ein oder mehrere
section
-Objekte, die jeweils mindestens ein Widget enthalten. Ein oder mehrere
widget
-Objekte. Jedes Widget ist ein zusammengesetztes Objekt, das Text, Bilder, Schaltflächen und andere Objekttypen darstellen kann.Die folgenden Widgets werden in Kartennachrichten und Dialogfeldern unterstützt:
TextParagraph
: Ein Textabschnitt mit optionaler einfacher HTML-Formatierung wird angezeigt.Image
: Es wird ein anklickbares oder statisches Bild angezeigt, das von.PNG
oder.JPG
auf einer HTTPS-URL gehostet wird.DecoratedText
: Text mit optionalen Layout- und Funktionsfunktionen wie Symbolen und SchaltflächenButtonList
: Eine Reihe von Schaltflächen wird angezeigt.
Die folgenden Widgets werden in Dialogfeldern unterstützt (Unterstützung für Kartennachrichten demnächst verfügbar):
TextInput
: Feld, in das Nutzer Text eingeben könnenSelectionInput
: Hier finden Sie auswählbare Elemente, z. B. eine Liste mit Kästchen, Optionsfeldern, Schaltern oder einem Drop-down-Menü.Divider
: Zeigt eine horizontale Linie über die Breite einer Karte zwischen gestapelten Widgets an, die als visuelle Trennlinie dient.Grid
: Hiermit werden mehrere Elemente in einem einfachen Raster angeordnet.
Das folgende Widget wird bald unterstützt:
DateTimePicker
: Nutzer können ein Datum, eine Uhrzeit oder beides angeben.
- Ein
Sehen Sie sich als Beispiel die Objekte header
, section
und widget
in der folgenden Kartennachricht an:
Der folgende Code steht für die JSON-Datei der Kartennachricht:
JSON
{
"cardsV2": [
{
"cardId": "unique-card-id",
"card": {
"header": {
"title": "Sasha",
"subtitle": "Software Engineer",
"imageUrl":
"https://developers.google.com/chat/images/quickstart-app-avatar.png",
"imageType": "CIRCLE",
"imageAltText": "Avatar for Sasha",
},
"sections": [
{
"header": "Contact Info",
"collapsible": true,
"uncollapsibleWidgetsCount": 1,
"widgets": [
{
"decoratedText": {
"startIcon": {
"knownIcon": "EMAIL",
},
"text": "sasha@example.com",
}
},
{
"decoratedText": {
"startIcon": {
"knownIcon": "PERSON",
},
"text": "<font color=\"#80e27e\">Online</font>",
},
},
{
"decoratedText": {
"startIcon": {
"knownIcon": "PHONE",
},
"text": "+1 (555) 555-1234",
}
},
{
"buttonList": {
"buttons": [
{
"text": "Share",
"onClick": {
"openLink": {
"url": "https://example.com/share",
}
}
},
{
"text": "Edit",
"onClick": {
"action": {
"function": "goToView",
"parameters": [
{
"key": "viewType",
"value": "EDIT",
}
],
}
}
},
],
}
},
],
},
],
},
}
],
}
Synchrone Kartennachricht senden
In diesem Beispiel sendet ein Nutzer der Chat App eine Nachricht in Google Chat und die App sendet eine einfache synchrone Kartennachricht mit dem Namen und Avatarbild des Absenders:
In den folgenden Codebeispielen werden die Node.js- und Python-Anwendungen in Google Cloud Functions gehostet. Das Apps Script-Beispiel wird in Google Apps Script gehostet.
Eine ausführliche Anleitung zum Erstellen und Bereitstellen einer Chat-App finden Sie unter Chat-App erstellen.
Node.js
Python
Apps Script
Asynchrone Kartennachricht mit der Chat API senden
In diesem Beispiel wird mit der Chat API eine Nachricht erstellt und an einen Gruppenbereich gesendet, dem die Chat App hinzugefügt wird. Beispiel:

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( 'service_account.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 Chat REST 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 Gruppenbereichsnamen, den Sie über die Methodespaces.list()
in der Chat API oder über die 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
Weitere Informationen zum Arbeiten mit Nachrichten in der Chat REST API finden Sie unter Nachrichten erstellen, lesen, aktualisieren, löschen.
Dialogfeld öffnen
Dialogfelder sind fensterbasierte, kartenbasierte Oberflächen, über die Chat-Apps mit Nutzern interagieren können. Apps können sequenzielle Dialogfelder öffnen, um Nutzern dabei zu helfen, mehrstufige Prozesse auszuführen. Apps können als Reaktion auf einen Schaltflächenklick auf eine Kartennachricht oder auf einen Slash-Befehl Dialogfelder öffnen.
Dialogfelder sind für viele Arten von Nutzerinteraktionen hilfreich, darunter:
- Informationen von Nutzern erfassen
- Nutzer mit Webdiensten authentifizieren
- Einstellungen der Chat App konfigurieren
In diesem Beispiel wird in einer Chat-App ein Dialogfeld geöffnet, über das Nutzer einen neuen Kontakt für ihr Adressbuch erstellen können:
Informationen zum Implementieren von Dialogfeldern finden Sie unter Dialogfelder öffnen.
Kartenformatierung
Formatierung von Kartentext
Innerhalb von Karten unterstützen die meisten Textfelder die einfache Textformatierung über eine kleine Teilmenge von HTML-Tags. Die unterstützten Tags und ihr Zweck sind in der folgenden Tabelle aufgeführt:
Fett | <b> | Kursiv | <i> | |
Unterstreichen | <> | Durchstreichen | <Verwarnung> | |
Schriftfarbe | <font color=""> | Hyperlink | <a href=""> | |
Zeilenumbruch | <br> |
Der Text einer einfachen Nachricht wird mit einer anderen Markup-Syntax geparst, die für menschliche Nutzer optimiert ist. Weitere Informationen finden Sie im Hilfeartikel SMS senden.
Integrierte Symbole
Die Widgets DecoratedText
und ButtonList
unterstützen das icon
-Element, mit dem eines der in Google Chat verfügbaren integrierten Symbole angegeben wird:
{ . . . "knownIcon": "TRAIN", . . . }
In der folgenden Tabelle sind die integrierten Symbole aufgeführt, die für Kartennachrichten verfügbar sind:
Flugzeug | BOOKMARK | ||
BUS | CAR | ||
UHR | CONFIRMATION_NUMBER_ICON | ||
DESCRIPTION | Dollar | ||
VERANSTALTUNG | |||
Flüge | AUFTRAG | ||
HOTEL | HOTEL_ROOM_TYPE | ||
EINLADEN | MAP_PIN | ||
MITGLIEDSCHAFT | MULTIPLE_PEOPLE | ||
PERSON | SMARTPHONE | ||
RESTAURANT_SYMBOL | SHOPPING_CART | ||
Stern | GESCHÄFT | ||
TICKET | SCHULUNG | ||
VIDEOKAMERA | VIDEO_PLAY |
Benutzerdefinierte Symbole
Mit den Widgets DecoratedText
und ButtonList
können Sie die oben aufgeführten integrierten Symbole verwenden oder eigene benutzerdefinierte Symbole definieren. Verwenden Sie das Element iconUrl
wie hier gezeigt, um ein benutzerdefiniertes Symbol anzugeben:
{ . . "iconUrl": "https://developers.google.com/chat/images/quickstart-app-avatar.png" . . }
Limits und Überlegungen
Beachten Sie beim Senden von Kartennachrichten diese Beschränkungen und Überlegungen.
Die folgenden Widgets werden von Kartennachrichten nicht unterstützt, die Unterstützung ist jedoch bald verfügbar:
TextInput
, ein Feld, in das Nutzer Text eingeben können.SelectionInput
– eine Reihe auswählbarer Elemente, z. B. eine Liste mit Kästchen, Optionsfeldern, Schaltern oder einem Drop-down-MenüDateTimePicker
: Nutzer können ein Datum, eine Uhrzeit oder beides angeben.Grid
: Hiermit werden mehrere Elemente in einem einfachen Raster angeordnet.