Kartennachricht senden

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

Hinweis: Die Codebeispiele in Node.js in diesem Leitfaden sind so geschrieben, dass sie als Google Cloud Functions-Funktion ausgeführt werden.

Python

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

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:

  1. Ein Array mit dem Namen cardsV2[], das ein oder mehrere CardWithId-Objekte enthält.
  2. 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.)

  3. 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ächen
      • ButtonList: 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önnen

      • SelectionInput: 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.

Sehen Sie sich als Beispiel die Objekte header, section und widget in der folgenden Kartennachricht an:

Eine Chat-App, die mit einer Kartennachricht in einem Chatbereich eine Umfrage ausführt

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:

Chat-App mit einer Karte, auf der der Anzeigename und das Avatarbild des Absenders zu sehen sind

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

Knoten/Avatar-Bot/Index.js
/**
 * Google Cloud Function that responds to messages sent from a
 * Hangouts Chat room.
 *
 * @param {Object} req Request sent from Hangouts Chat room
 * @param {Object} res Response to send back
 */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Hangouts Chat ' +
      'Room.');
  }

  const sender = req.body.message.sender.displayName;
  const image = req.body.message.sender.avatarUrl;

  const data = createMessage(sender, image);

  res.send(data);
};

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} imageUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, imageUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`,
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '},
  };

  const avatarImageWidget = {
    image: {imageUrl},
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Python

python/avatar-bot/main.py
from typing import Any, Mapping

import flask
import functions_framework

# Google Cloud Function that responds to messages sent in
# Google Chat.
#
# @param {Object} req Request sent from Google Chat.
# @param {Object} res Response to send back.
@functions_framework.http
def hello_chat(req: flask.Request):
    if req.method == "GET":
        return "Hello! This function must be called from Google Chat."

    request_json = req.get_json(silent=True)

    display_name = request_json["message"]["sender"]["displayName"]
    avatar = request_json["message"]["sender"]["avatarUrl"]

    response = create_message(name=display_name, image_url=avatar)

    return response


# Creates a card with two widgets.
# @param {string} name the sender's display name.
# @param {string} image_url the URL for the sender's avatar.
# @return {Object} a card with the user's avatar.
def create_message(name: str, image_url: str) -> Mapping[str, Any]:
    avatar_image_widget = {"image": {"imageUrl": image_url}}
    avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
    avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}

    header = {"title": f"Hello {name}!"}

    cards = {
        "cardsV2": [
            {
                "cardId": "avatarCard",
                "card": {
                    "name": "Avatar Card",
                    "header": header,
                    "sections": [avatar_section],
                },
            }
        ]
    }

    return cards

Apps Script

apps-script/avatar-bot/hello-chat.gs
/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  const displayName = event.message.sender.displayName;
  const avatarUrl = event.message.sender.avatarUrl;

  return createMessage(displayName, avatarUrl);
}

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} avatarUrl the URL for the sender's avatar
 * @return {Object} a card with the sender's avatar.
 */
function createMessage(displayName, avatarUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '}
  };

  const avatarImageWidget = {
    image: {imageUrl: avatarUrl}
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget
    ],
  };

  return {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

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:

Eine mit der Chat REST API erstellte Kartennachricht.
Abbildung 1: Mit der Chat REST API erstellte Kartennachricht.

Python

  1. Erstellen Sie in Ihrem Arbeitsverzeichnis eine Datei mit dem Namen chat_create_card_message.py.

  2. 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)

  3. Ersetzen Sie im Code SPACE durch einen Gruppenbereichsnamen, den Sie über die Methode spaces.list() in der Chat API oder über die URL eines Gruppenbereichs abrufen können.

  4. 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:

Ein Dialogfeld mit einer Vielzahl verschiedener Widgets.

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
E-MAIL 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.