Eine Nachricht posten

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

  • Sie können Text- und Kartennachrichten in Echtzeit senden, indem Sie auf eine Nutzerinteraktion reagieren.
  • Senden Sie Text- und Kartennachrichten asynchron, indem Sie die Methode create für die Ressource Message aufrufen.
  • Sie können eine Unterhaltung starten oder darauf antworten.
  • Senden und benennen Sie eine Nachricht.

Die Ressource Message steht für eine Textnachricht oder eine Kartennachricht in Google Chat. Sie können eine Nachricht in der Google Chat API mit create, get, update oder delete durch Aufrufen der entsprechenden Methoden abrufen. Weitere Informationen zu Text- und Kartennachrichten finden Sie unter 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-Anwendungen 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-Anwendung 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 in der 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-Anwendung 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 SMS beschrieben:

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

SMS in Echtzeit senden

In diesem Beispiel erstellt und sendet Ihre Chat-Anwendung eine Textnachricht, sobald sie einem Gruppenbereich hinzugefügt wird. Weitere Informationen zu den Best Practices für das Onboarding von Nutzern finden Sie unter Nutzer und Gruppenbereiche durch hilfreiches Onboarding unterstützen.

Zum Senden einer SMS, wenn ein Nutzer Ihre Chat-App einem Gruppenbereich hinzufügt, reagiert die Chat-App auf ein ADDED_TO_SPACE-Interaktionsereignis. 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 der App- und Nutzerauthentifizierung gesendet wird.

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

  • Geben Sie bei der App-Authentifizierung den Autorisierungsbereich chat.bot an. Geben Sie bei der 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 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_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 SMS mit 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 des Gruppenbereichs. Diesen finden Sie in der Chat API mit der Methode spaces.list() oder aus der URL eines Gruppenbereichs.

  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:

  • Du kannst eine Kartennachricht in Echtzeit senden, indem du auf eine Nutzerinteraktion reagierst.
  • Sie können eine Kartennachricht senden, indem Sie die Google Chat API asynchron aufrufen.

Kartennachricht in Echtzeit senden

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

Übergeben Sie zum Senden einer Kartennachricht Folgendes in Ihrer Anfrage:

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

Hier ein Beispiel für eine Kartennachricht:

Eine Kartennachricht, die mit der Chat API gesendet wurde.

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

Unterhaltungsthreads in einer Nachricht starten oder beantworten

Wenn Sie einen Nachrichtenthread starten möchten, senden Sie eine Nachricht und lassen Sie thread.name leer. Google Chat füllt dies beim Erstellen des Threads. Optional können Sie das Feld thread.threadKey angeben, um den Namen des Threads anzupassen.

Zum Antworten auf einen Nachrichtenthread senden Sie eine Nachricht, die das Feld threadKey oder name des Threads angibt. Wenn der Thread von einer Person oder einer anderen Chat-App erstellt wurde, müssen Sie das Feld thread.name verwenden.

Wenn keine passende Unterhaltung 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 mit dem Feld threadKey, das 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 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_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. Nachrichtennamen werden zum Abrufen, Aktualisieren oder Löschen von Nachrichten verwendet. Durch die Zuweisung eines benutzerdefinierten Namens kann eine Chat-Anwendung die Nachricht auch zurückrufen, ohne die Nachricht name aus dem Antworttext zu speichern, der beim Senden der Nachricht zurückgegeben wird.

Das Zuweisen eines benutzerdefinierten Namens ersetzt nicht das generierte Feld name, also den Ressourcennamen der Nachricht. 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 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_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 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.