Kartennachricht erstellen

Auf dieser Seite wird erläutert, wie Sie als Google Chat-App kartenbasierte Nachrichten erstellen und senden. Karten unterstützen ein definiertes Layout, interaktive UI-Elemente wie Schaltflächen und Rich Media wie Bilder. Weitere Informationen zu den Verwendungsmöglichkeiten von Karten finden Sie unter Dynamische, interaktive und einheitliche UIs mit Karten entwerfen. Weitere Informationen zu Nachrichten finden Sie unter Nachrichten in Google Chat.

Voraussetzungen

Node.js

Hinweis:Die Codebeispiele für Node.js in diesem Leitfaden sollen als Google Cloud Functions-Funktion ausgeführt werden.

Python

Hinweis:Die Python-Codebeispiele in diesem Leitfaden sind zur Ausführung als Google Cloud Functions-Funktion mit Python 3.9 geschrieben.

Apps Script

Kartennachrichten erstellen

In diesem Abschnitt wird auf zwei Arten beschrieben, wie Kartennachrichten erstellt werden: durch Reagieren auf eine Nutzerinteraktion und asynchrones Aufrufen der Google Chat API.

Einem Nutzer antworten

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:

Eine Chat-App antwortet mit einer Karte, die den Anzeigenamen und das Avatarbild des Absenders enthält.

Node.js

Node/Avatar-App/Index.js
/**
 * Google Cloud Function that responds to messages sent from a
 * Google Chat room.
 *
 * @param {Object} req Request sent from Google 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 Google 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-app/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) -> Mapping[str, Any]:
  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-app/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],
      }
    }],
  };
}

Google Chat API aufrufen

Im Folgenden wird erläutert, wie Sie eine Kartennachricht durch asynchrones Aufrufen der Google Chat API erstellen.

Für den asynchronen Aufruf der Chat API ist eine Authentifizierung erforderlich. Da nur Chat-Anwendungen Kartennachrichten erstellen können, muss eine Chat-Anwendung zum Erstellen und Senden von Kartennachrichten die Anwendungsauthentifizierung verwenden. Chat-Apps können die Nutzerauthentifizierung nicht verwenden, um Kartennachrichten im Namen von Nutzern zu senden. Weitere Informationen finden Sie unter Authentifizierung mit Google Chat.

In diesem Beispiel erstellen Sie die folgende Kartennachricht mithilfe der Anwendungsauthentifizierung:

Eine Kartennachricht, die mit der Google Chat API erstellt wurde.
Abbildung 1: Eine mit der Chat API erstellte Kartennachricht.

Informationen zum Einrichten der Authentifizierung und zum asynchronen Erstellen von Nachrichten finden Sie im Leitfaden zur Chat API.

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(
        '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 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 den Namen eines Gruppenbereichs, den Sie in der Chat API mit der Methode spaces.list() oder aus der 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 API finden Sie hier:

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.