Eine Nachricht posten

In diesem Leitfaden werden die verschiedenen Möglichkeiten erläutert, mit denen Google Chat-Apps Nachrichten senden können:

  • Senden Sie Text- und Kartennachrichten in Echtzeit, indem Sie auf eine Nutzerinteraktion reagieren.
  • Senden Sie Text- und Kartennachrichten asynchron, indem Sie die Methode create für die Ressource Message aufrufen.
  • Eine Konversation starten oder beantworten.
  • Senden und benennen Sie eine Nachricht.

Die Ressource Message stellt eine Textnachricht oder eine Kartennachricht in Google Chat dar. Sie können eine Nachricht in der Google Chat API mit create, get, update oder delete durch Aufrufen der entsprechenden Methoden steuern. Weitere Informationen zu Text- und Kartennachrichten finden Sie in der Übersicht zu 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-Apps 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-App zum Senden asynchroner Nachrichten konfiguriert ist. Zum Senden von Nachrichten in Echtzeit ist keine Autorisierungskonfiguration erforderlich.

Python

  • Python 3.6 oder höher
  • Das Paketverwaltungstool pip

  • Die neuesten Google-Clientbibliotheken für Python. Führen Sie den folgenden Befehl über die 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-App zum Senden asynchroner Nachrichten konfiguriert ist. Zum Senden von Nachrichten in Echtzeit ist keine Autorisierungskonfiguration erforderlich.

Apps Script

SMS senden

In diesem Abschnitt werden die beiden folgenden Möglichkeiten zum Senden von Textnachrichten beschrieben:

  • Sie senden eine Textnachricht in Echtzeit, indem Sie auf eine Nutzerinteraktion reagieren.
  • Senden Sie eine SMS, indem Sie die Google Chat API asynchron aufrufen.

SMS in Echtzeit senden

In diesem Beispiel erstellt und sendet die Chat-Anwendung eine SMS, sobald sie einem Gruppenbereich hinzugefügt wird. Informationen zu Best Practices für das Onboarding von Nutzern finden Sie unter Hilfreiches Onboarding für Nutzer und Gruppenbereiche.

Wenn eine SMS gesendet werden soll, wenn ein Nutzer Ihre Chat-App einem Gruppenbereich hinzufügt, reagiert die Chat-App auf ein Interaktionsereignis ADDED_TO_SPACE. 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:

Beispiel für eine Onboarding-Nachricht

SMS asynchron senden

Im folgenden Abschnitt wird erläutert, wie eine SMS asynchron mit App- und Nutzerauthentifizierung gesendet wird.

Um eine Textnachricht zu senden, übergeben Sie in Ihrer Anfrage Folgendes:

  • Geben Sie für die App-Authentifizierung den Autorisierungsbereich chat.bot an. Geben Sie für die Nutzerauthentifizierung den Autorisierungsbereich chat.messages.create an.
  • Rufen Sie die Methode create für die Ressource Message auf.

SMS mit App-Authentifizierung senden

So senden Sie eine SMS mit der App-Authentifizierung:

Python

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

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

  3. Ersetzen Sie im Code SPACE durch den Namen eines Gruppenbereichs, den Sie über die Methode spaces.list() in der Chat API 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_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 Textnachricht mit der Nutzerauthentifizierung:

Python

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

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

  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_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:

  • Sie können in Echtzeit eine Kartennachricht senden, indem Sie auf eine Nutzerinteraktion reagieren.
  • Senden Sie eine Kartennachricht, indem Sie die Google Chat API asynchron aufrufen.

Eine Kartennachricht in Echtzeit senden

Chat-Apps können Kartennachrichten erstellen, um auf eine Nutzerinteraktion zu antworten, 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-App und die Chat-App 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 {
    text: 'Here\'s your avatar',
    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 = {
      "text": "Here's your avatar",
      "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 {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Eine Kartennachricht asynchron senden

Um eine Kartennachricht zu senden, übergeben Sie in der Anfrage Folgendes:

  • Geben Sie für die App-Authentifizierung den Autorisierungsbereich chat.bot an. Sie können mit der Nutzerauthentifizierung keine Kartennachricht senden.
  • Rufen Sie die Methode create für die Ressource Message auf.

Hier ein Beispiel für eine Kartennachricht:

Eine mit der Chat API gesendete Kartennachricht.

So senden Sie eine Kartennachricht mit App-Authentifizierung:

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

  3. Ersetzen Sie im Code SPACE durch den Namen eines Gruppenbereichs, den Sie über die Methode spaces.list in der Chat API 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

Unterhaltung starten oder beantworten

Wenn Sie einen Nachrichten-Thread starten möchten, senden Sie eine Nachricht und lassen Sie thread.name leer. Google Chat füllt ihn beim Erstellen des Threads. Optional können Sie den Namen des Threads über das Feld thread.threadKey anpassen.

Wenn Sie auf einen Nachrichten-Thread antworten möchten, senden Sie eine Nachricht, in der das Feld threadKey oder name des Threads angegeben ist. Wenn der Thread von einer Person oder einer anderen Chat-App erstellt wurde, müssen Sie das Feld thread.name verwenden.

Wenn kein übereinstimmender Thread 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, wobei das Feld threadKey als nameOfThread definiert ist:

Python

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

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

  3. Ersetzen Sie im Code SPACE durch den Namen eines Gruppenbereichs, den Sie über die Methode spaces.list in der Chat API 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_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. Mit Nachrichtennamen können Sie Nachrichten abrufen, aktualisieren oder löschen. Durch Zuweisen eines benutzerdefinierten Namens kann eine Chat-App die Nachricht außerdem zurückrufen, ohne die Nachricht name aus dem Antworttext zu speichern, der beim Senden der Nachricht zurückgegeben wird.

Durch die Zuweisung eines benutzerdefinierten Namens wird das generierte Feld name, also der Ressourcenname der Nachricht, nicht ersetzt. 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 ist client-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 und delete funktionieren jedoch wie erwartet.

So senden und benennen Sie eine Nachricht:

Python

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

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

  3. Ersetzen Sie im Code SPACE durch den Namen eines Gruppenbereichs, den Sie über die Methode spaces.list in der Chat API 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_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 -Karte einen Fehler zurückgibt, wird in der Chat-Oberfläche die Meldung „Ein Fehler ist aufgetreten“ oder „Anfrage kann nicht verarbeitet werden“ angezeigt. Manchmal wird in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt, die Chat-App oder -Karte aber zu einem unerwarteten Ergebnis führt, z. B. wird keine Kartennachricht angezeigt.

Obwohl eine Fehlermeldung möglicherweise nicht in der Chat-Benutzeroberfläche angezeigt wird, stehen beschreibende Fehlermeldungen und Protokolldaten zur Verfügung, mit denen Sie Fehler beheben können, wenn die Fehlerprotokollierung für Chat-Apps aktiviert ist. Weitere Informationen finden Sie im Hilfeartikel Fehler in Google Chat beheben.