Nachricht über die Google Chat API senden

In diesem Leitfaden wird erläutert, wie Sie die messages.create() um eine der folgenden Aktionen auszuführen:

  • Senden Sie Nachrichten, die Text, Karten und interaktive Widgets enthalten.
  • Nachrichten privat an einen bestimmten Chat-Nutzer senden.
  • Sie können eine Unterhaltung starten oder darauf antworten.
  • Benennen Sie eine Nachricht, damit Sie sie in einer anderen Chat API angeben können -Anfragen.

<ph type="x-smartling-placeholder">

Neben der Methode messages.create() können Chat-Apps Nachrichten erstellen und senden, um auf Interaktionen von Nutzern zu antworten, z. B. Willkommensnachricht, nachdem ein Nutzer die Chat-App einer Leerzeichen. Beim Reagieren auf Interaktionen können Chat-Apps andere Arten von Messaging-Funktionen wie interaktive Dialogfelder und Linkvorschau Schnittstellen. Um einem Nutzer zu antworten, gibt die Chat App die Nachricht synchron, ohne die Chat API aufzurufen. Weitere Informationen wie Sie Nachrichten senden, um auf Interaktionen zu reagieren, Interaktionen mit der Google Chat App empfangen und beantworten

So werden in Google Chat mit der Chat API erstellte Nachrichten angezeigt und zugeordnet

Sie können die Methode messages.create() mit App-Authentifizierung und Nutzerauthentifizierung. In Google Chat wird der Absender der Nachricht unterschiedlich zugeordnet je nach verwendetem Authentifizierungstyp.

Wenn Sie sich als Chat-App authentifizieren, die Chat-App die Nachricht sendet.

<ph type="x-smartling-placeholder">
</ph> Durch Aufrufen der Methode messages.create() mit Anwendungsauthentifizierung
Abbildung 1: Bei der App-Authentifizierung sendet die Chat-App in der Nachricht. Hinweis: Der Absender ist keine Person. In Google Chat wird neben dem Namen das Symbol App angezeigt.

Wenn Sie sich als Nutzer authentifizieren, sendet die Chat-App die im Namen des Nutzers senden. In Chat wird auch die Chat-App an die Nachricht, indem der Name angezeigt wird.

<ph type="x-smartling-placeholder">
</ph> Durch Aufrufen der Methode messages.create() mit Nutzerauthentifizierung
Abbildung 2: Mit der Nutzerauthentifizierung sendet der Nutzer die Nachricht und Google Chat zeigt die Name der Chat-App neben dem Namen des Nutzers

Der Authentifizierungstyp bestimmt auch, welche Messaging-Funktionen und -Oberflächen die Sie in die Nachricht aufnehmen können. Bei der App-Authentifizierung Chat-Apps können Nachrichten senden, die RTF, kartenbasierten Oberflächen und interaktiven Widgets. Da Google Chat-Nutzer nur Text in ihren Nachrichten senden können, haben Sie folgende Möglichkeiten: nur Text enthalten, wenn Nachrichten mithilfe der Nutzerauthentifizierung erstellt werden. Weitere Informationen zur Nachrichtenfunktion die für die Chat API zur Verfügung stehen, finden Sie in der Nachrichten in Google Chat

In diesem Leitfaden wird erläutert, wie du beide Authentifizierungstypen zum Senden einer Nachricht verwendest mit der Chat-API.

Vorbereitung

Python

SMS im Namen eines Nutzers senden

In diesem Abschnitt wird erläutert, wie Sie Nachrichten im Namen eines Nutzers mit Nutzerauthentifizierung Bei der Nutzerauthentifizierung darf der Inhalt der Nachricht nur Text enthalten und darf Nachrichtenfunktionen auslassen, die nur für Chat-Apps wie Kartenoberflächen und interaktive Widgets

Nachricht mit Nutzerauthentifizierung gesendet
Abbildung 3: Eine Chat-App sendet eine SMS an im Namen eines Nutzers.

Um die messages.create() mithilfe der Nutzerauthentifizierung aufzurufen, müssen Sie die folgende Felder in der Anfrage:

  • Einen Autorisierungsbereich die die Nutzerauthentifizierung für diese Methode unterstützt. Im folgenden Beispiel werden den Bereich chat.messages.create.
  • Die Ressource Space, in der die Sie posten möchten. Der authentifizierte Nutzer muss Mitglied des Leerzeichen.
  • Die Message zu erstellende Ressource. Um den Inhalt der Nachricht zu definieren, müssen Sie den Parameter text ein.

Optional können Sie Folgendes angeben:

So senden Sie eine SMS im Namen eines Nutzers:

Python

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

  2. Fügen Sie den folgenden Code in chat_create_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',

        # Optional. Sets custom ID for the message to use in other requests.
        messageId='client-myfirstusermessage',

        # The text message to create.
        body={
          'text': '👋 🌎Hello world! Text messages can contain things like:\n\n'

          + '* Hyperlinks 🔗\n'
          + '* Emojis 😄🎉\n'
          + '* Mentions of other Chat users `@` \n\n'

          'For details, see the <https://developers.google.com/workspace/chat/format-messages|Chat API developer documentation>.'
      }

    ).execute()

    # Prints details about the created message.
    print(result)

if __name__ == '__main__':
    main()

    Ersetzen Sie SPACE durch die ID aus der name ein. Sie erhalten die ID durch Aufrufen der spaces.list()-Methode oder aus der URL des Gruppenbereichs.

  3. Erstellen Sie das Beispiel in Ihrem Arbeitsverzeichnis und führen Sie es aus:

    python3 chat_create_message_user.py

  4. Wenn Sie dazu aufgefordert werden, öffnen Sie die URL, um den Chat-App basierend auf dem Bereich, den Sie in Ihrem

Die Chat-App erstellt die Nachricht und die authentifizierte Der Nutzer postet die Nachricht im Gruppenbereich. In der Befehlszeile Die Chat API gibt die Instanz des neuen Message.

Nachricht als Chat-App senden

In diesem Abschnitt wird erläutert, wie Sie Nachrichten senden, die Text, Karten und interaktive Zubehör-Widgets App-Authentifizierung.

Nachricht mit App-Authentifizierung gesendet
Abbildung 4: Eine Chat-App sendet eine Nachricht mit Text, eine Karte und eine Zubehörschaltfläche.

Zum Aufrufen von messages.create() mithilfe der App-Authentifizierung müssen Sie die Methode folgende Felder in der Anfrage:

  • Der Autorisierungsbereich chat.bot.
  • Die Ressource Space, in der die Sie posten möchten. Die Chat-App muss Mitglied des Gruppenbereichs.
  • Die Message zu erstellende Ressource. Um den Inhalt der Nachricht zu definieren, können Sie RTF (text), eine oder mehrere Kartenschnittstellen (cardsV2), oder beides.

Optional können Sie Folgendes angeben:

Die maximale Nachrichtengröße (inklusive Text oder Karten) beträgt 32.000 Byte. Wenn Sie eine Nachricht senden möchten, die diese Größe überschreitet, muss stattdessen mehrere Nachrichten senden.

So senden Sie eine in der Chat-App gepostete Nachricht mit folgendem Inhalt: Text, eine Karte und eine klickbare Schaltfläche unten in der Nachricht, führen Sie die folgenden Schritte aus:

Python

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

  2. Fügen Sie den folgenden Code in chat_create_message_app.py ein:

    from apiclient.discovery import build
from google.oauth2 import service_account

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = service_account.Credentials.from_service_account_file(
    'credentials.json', scopes=SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', credentials=CREDENTIALS)

# Specify the Chat space where the message is posted. Obtain the ID
# from the resource name, or from the space's URL.
SPACE = 'spaces/SPACE'

# Create a Chat message.
result = chat.spaces().messages().create(

    # The Chat space.
    parent=SPACE,

    # Optional. Sets custom ID for the message to use in other requests.
    messageId='client-myfirstappmessage',

    # The message to create with text, a card, and a button at the
    # bottom of the message.
    body=
    {
      'text': '👋 🌎Hello world! I created this message by calling the Chat API\'s `messages.create()` method.',
      'cardsV2': [{
        'cardId': 'myCardId',
        'card': {
          'header': {
            'title': 'About this message',
            'imageUrl': 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg',
            'imageType': 'CIRCLE'
          },
        "sections": [
            {
            "header": "Contents",
            "widgets": [
                {
                "textParagraph": {
                    "text": "🔡 <b>Text</b> which can include hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️."
                }},
                {
                "textParagraph": {
                    "text": "🖼️ A <b>card</b> to display visual elements and request information such as text 🔤, dates and times 📅, and selections ☑️."
                }},
                {
                "textParagraph": {
                    "text": "👉🔘 An <b>accessory widget</b> which adds a button to the bottom of a message."
                }},
              ]
            },
            {
            "header": "What's next",
            "collapsible": True,
            "widgets": [
                {
                "textParagraph": {
                    "text": "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>."
                }},
                {
                "textParagraph": {
                    "text": "🔄 <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/patch'>Update</a> or ❌ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/delete'>delete</a> the message."
                }},
                {
                "textParagraph": {
                    "text": '💡 <b>Pro tip</b>: To specify the message in other API requests, use its custom name: <i>' + SPACE + '/messages/client-myfirstappmessage</i>.'
                }}
              ]
            }
          ]}
      }],
      "accessoryWidgets":
      [
          {
              "buttonList":
              {
                  "buttons":
                  [
                      {
                          "text": "View documentation",
                          "altText": "Opens a new browser tab and navigates to the Google Chat developer documentation website.",
                          "icon":
                          {
                              "material_icon":
                              {
                                  "name": "link"
                              }
                          },
                          "onClick":
                          {
                              "openLink":
                              {
                                  "url": "https://developers.google.com/workspace/chat/create-messages"
                              }
                          }
                      }
                  ]
              }
          }
      ]
    }

).execute()

print(result)

    Ersetzen Sie SPACE durch die ID aus der name ein. Sie erhalten die ID durch Aufrufen der spaces.list()-Methode oder aus der URL des Gruppenbereichs.

  3. Erstellen Sie das Beispiel in Ihrem Arbeitsverzeichnis und führen Sie es aus:

    python3 chat_create_message_app.py

Die Chat-App erstellt und postet die Nachricht im Leerzeichen. In der Befehlszeile gibt die Chat API den Fehlercode Instanz des neuen Message.

Interaktive Widgets am Ende einer Nachricht hinzufügen

In dem Codebeispiel aus dem vorherigen Abschnitt Bei der Chat-App-Nachricht wird im Bereich in der Meldung angezeigt wird – das sogenannte Zubehör-Widget. Zubehör-Widgets werden nach Text oder Karten in einer Nachricht angezeigt. Mit diesen Widgets können Sie die Nutzer auf verschiedene Arten mit Ihrer Botschaft interagieren können, z. B.:

  • Bewerten Sie die Genauigkeit oder Zufriedenheit einer Nachricht.
  • Problem mit der Messages App oder der Chat App melden
  • Öffnen Sie einen Link zu ähnlichen Inhalten, z. B. zur Dokumentation.
  • Ähnliche Nachrichten aus der Chat App schließen oder zurückstellen für einen bestimmten Zeitraum.

Fügen Sie zum Hinzufügen von Zubehör-Widgets den accessoryWidgets[] im Text Ihrer Anfrage und geben Sie ein oder mehrere Widgets an, die Sie enthalten sein sollen.

In der folgenden Abbildung sehen Sie eine Chat-App, eine Textnachricht mit Zubehör-Widgets, damit Nutzer ihre Erfahrung bewerten können mit der Chat-App.

<ph type="x-smartling-placeholder">
</ph> Zubehör-Widget.
Abbildung 5: Eine Chat-App-Nachricht mit Text- und Zubehör-Widgets.

Hier sehen Sie den Text der Anfrage, mit der eine Textnachricht mit zwei Zubehörtasten. Wenn Nutzende auf eine Schaltfläche klicken, wird die entsprechende (z. B. doUpvote) die Interaktion verarbeitet:


 "text": "Rate your experience with this Chat app.",
 "accessoryWidgets": [
   {
     "buttonList": {
       "buttons": [
         {
           "icon": {
             "material_icon": {
               "name": "thumb_up"
             }
           },
           "color": {
             "red": 0,
             "blue": 255,
             "green": 0
           },
           "onClick": {
             "action": {
               "function": "doUpvote",
             }
           }
         },
         {
           "icon": {
             "material_icon": {
               "name": "thumb_down"
             }
           },
           "color": {
             "red": 0,
             "blue": 255,
             "green": 0
           },
           "onClick": {
             "action": {
               "function": "doDownvote",
             }
           }
         }
       ]
     }
   }
 ]

Nachricht privat senden

Chat-Apps können private Nachrichten senden, damit die Die Nachricht ist nur für einen bestimmten Nutzer im Gruppenbereich sichtbar. Wenn ein die Chat-App eine private Nachricht sendet, zeigt ein Label, das den Nutzer darüber informiert, dass die Nachricht nur für ihn sichtbar ist.

Wenn Sie eine Nachricht privat über die Chat API senden möchten, geben Sie Folgendes an: privateMessageViewer im Text Ihrer Anfrage. Um den Nutzer anzugeben, setzen Sie den Wert auf User-Ressource, die für den Chat-Nutzer steht. Sie können auch die name des User, wie im folgenden Beispiel gezeigt:

{
    "text": "Hello private world!",
    "privateMessageViewer": {
      "name": "users/USER_ID"
    }
}

USER_ID ersetzen mit einer eindeutigen ID für den Nutzer, z. B. 12345678987654321 oder hao@cymbalgroup.com Weitere Informationen zum Angeben von Nutzern finden Sie unter Google Chat-Nutzer identifizieren und angeben

Um eine Nachricht privat zu senden, müssen Sie in Ihrer Anfrage Folgendes weglassen:

Threads starten oder antworten

Für Gruppenbereiche mit Threads: können Sie festlegen, ob mit einer neuen Nachricht ein Thread gestartet oder auf einen vorhandenen Thread.

Standardmäßig wird bei Nachrichten, die Sie mit der Chat API erstellen, ein neuer Diskussions-Thread. Damit Sie die Konversation leichter identifizieren und später darauf antworten können, können Sie ein Thread-Schlüssel in Ihrer Anfrage:

  • Geben Sie im Text Ihrer Anfrage thread.threadKey ein.
  • Abfrageparameter angeben messageReplyOption um festzustellen, was passiert, falls der Schlüssel bereits vorhanden ist.

So erstellen Sie eine Antwort auf eine vorhandene Unterhaltung:

  • Fügen Sie in den Anfragetext das Feld thread ein. Wenn festgelegt, können Sie geben Sie die threadKey die Sie erstellt haben. Andernfalls müssen Sie die Methode name des Threads.
  • Geben Sie den Abfrageparameter messageReplyOption an.

Die folgende JSON-Datei zeigt ein Beispiel für den Anfragetext für eine Textnachricht, die einen Thread mit dem Schlüssel helloWorldThread startet oder antwortet:

   {
     'thread': {
      'threadKey': 'helloWorldThread',
     },
     'text': '👋 🌎Hello world!'
   }

Nachrichten benennen

Sie können eine Nachricht benennen, um eine Nachricht in zukünftigen API-Aufrufen abzurufen oder anzugeben. indem Sie das Feld messageId in Ihrer messages.create()-Anfrage festlegen. Durch einen Namen können Sie die Nachricht angeben, ohne den vom System zugewiesene ID aus dem Ressourcennamen der Nachricht (dargestellt in der name Feld.

Wenn Sie beispielsweise eine Nachricht mit der Methode get() abrufen möchten, verwenden Sie die Methode Ressourcenname, um anzugeben, welche Nachricht abgerufen werden soll. Der Ressourcenname lautet formatiert als spaces/{space}/messages/{message}, wobei {message} für die vom System zugewiesene ID oder den benutzerdefinierten Namen, den Sie beim Erstellen des angezeigt.

Um eine Nachricht zu benennen, geben Sie eine benutzerdefinierte ID in der messageId wenn Sie die Mitteilung erstellen. Das Feld messageId legt den Wert für die clientAssignedMessageId der Ressource Message.

Sie können eine Nachricht nur benennen, wenn Sie sie erstellen. Sie können weder einen Namen eine benutzerdefinierte ID für vorhandene Nachrichten ändern. Die benutzerdefinierte ID muss folgende Anforderungen erfüllen Anforderungen:

  • Beginnt mit client-. client-custom-name ist beispielsweise ein gültiger benutzerdefinierter ID, custom-name jedoch nicht.
  • Enthält bis zu 63 Zeichen und darf nur Kleinbuchstaben, Ziffern und Bindestriche verwenden.
  • Ist innerhalb eines Gruppenbereichs eindeutig. Eine Chat-App kann die dieselbe benutzerdefinierte ID für unterschiedliche Nachrichten verwenden.

Fehlerbehebung

Wenn eine Google Chat-App oder card gibt einen Fehler zurück. Der Parameter In der Chatoberfläche wird die Meldung „Ein Fehler ist aufgetreten“ angezeigt. oder „Ihre Anfrage kann nicht verarbeitet werden.“ Manchmal kann die Chat-UI Es wird zwar keine Fehlermeldung angezeigt, aber die Chat-App oder die Karte zu einem unerwarteten Ergebnis führt. z. B. wird eine Kartennachricht angezeigt werden.

Auch wenn in der Chat-Benutzeroberfläche möglicherweise keine Fehlermeldung angezeigt wird, beschreibende Fehlermeldungen und Protokolldaten stehen zur Fehlerbehebung zur Verfügung. wenn die Fehlerprotokollierung für Chat-Apps aktiviert ist. Hilfe bei der Anzeige: Debugging und Beheben von Fehlern finden Sie unter Google Chat-Fehler beheben