Nachricht über die Google Chat API senden

In diesem Leitfaden wird beschrieben, wie Sie die Methode create() für die Ressource Message der Google Chat API verwenden, um Folgendes zu tun:

  • Nachrichten mit Text, Karten und interaktiven Widgets senden
  • Nachrichten privat an einen bestimmten Google Chat-Nutzer senden
  • Eine Unterhaltung starten oder darauf antworten.
  • Geben Sie einer Nachricht einen Namen, damit Sie sie in anderen Chat API-Anfragen angeben können.

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

Chat-Apps können nicht nur die Chat API aufrufen, um Nachrichten zu erstellen, sondern auch Nachrichten erstellen und senden, um auf Nutzerinteraktionen zu antworten, z. B. eine Willkommensnachricht posten, nachdem ein Nutzer die Chat-App einem Gruppenbereich hinzugefügt hat. Bei der Beantwortung von Interaktionen können Chat-Apps andere Arten von Messaging-Funktionen verwenden, darunter interaktive Dialogfelder und Linkvorschaufen. Wenn Sie auf einen Nutzer antworten möchten, gibt die Chat-App die Nachricht synchron zurück, ohne die Chat API aufzurufen. Informationen zum Senden von Nachrichten als Reaktion auf Interaktionen finden Sie unter Interaktionen mit Ihrer Google Chat App empfangen und darauf reagieren.

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

Sie können die create()-Methode mit der App-Authentifizierung und der Nutzerauthentifizierung aufrufen. Je nach Art der Authentifizierung, die Sie verwenden, ordnet Chat den Absender der Nachricht unterschiedlich zu.

Wenn Sie sich als die Chat App authentifizieren, wird die Nachricht von der Chat App gesendet.

Die Methode „create()“ mit App-Authentifizierung aufrufen.
Abbildung 1: Bei der App-Authentifizierung wird die Nachricht von der Chat App gesendet. Wenn der Absender keine Person ist, wird in Chat neben dem Namen des Absenders App angezeigt.

Wenn Sie sich als Nutzer authentifizieren, sendet die Chat-App die Nachricht im Namen des Nutzers. Außerdem wird die Chat-App der Nachricht zugeordnet, indem ihr Name angezeigt wird.

Die Methode „create()“ mit Nutzerauthentifizierung aufrufen.
Abbildung 2: Bei der Nutzerauthentifizierung sendet der Nutzer die Nachricht und in Chat wird der Name der Chat-App neben dem Namen des Nutzers angezeigt.

Der Authentifizierungstyp bestimmt auch, welche Messaging-Funktionen und ‑Schnittstellen Sie in die Nachricht einfügen können. Mit der App-Authentifizierung können Chat-Apps Nachrichten mit Rich-Text, kartenbasierten Oberflächen und interaktiven Widgets senden. Da Chat-Nutzer in ihren Nachrichten nur Text senden können, können Sie beim Erstellen von Nachrichten mit Nutzerauthentifizierung nur Text einfügen. Weitere Informationen zu den Messaging-Funktionen, die für die Chat API verfügbar sind, finden Sie unter Google Chat-Nachrichten – Übersicht.

In dieser Anleitung wird erläutert, wie Sie mit der Chat API eine Nachricht senden, indem Sie einen der beiden Authentifizierungstypen verwenden.

Vorbereitung

Node.js

Python

Java

Apps Script

Nachricht als Chat-App senden

In diesem Abschnitt wird beschrieben, wie Sie Nachrichten mit Text, Karten und interaktiven Zubehör-Widgets über die App-Authentifizierung senden.

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

Wenn Sie die Methode CreateMessage() mit der App-Authentifizierung aufrufen möchten, müssen Sie die folgenden Felder in der Anfrage angeben:

  • Der chat.bot-Autorisierungsbereich.
  • Die Space-Ressource, in der Sie die Nachricht posten möchten. Die Chat-App muss Mitglied des Bereichs sein.
  • Die zu erstellende Message-Ressource. Um den Inhalt der Nachricht zu definieren, können Sie Rich-Text (text), eine oder mehrere Kartenoberflächen (cardsV2) oder beides einfügen.

Optional können Sie Folgendes angeben:

Der folgende Code zeigt ein Beispiel dafür, wie eine Chat-App eine Nachricht senden kann, die als Chat-App gepostet wurde und Text, eine Karte und eine anklickbare Schaltfläche am Ende der Nachricht enthält:

Node.js

chat/client-libraries/cloud/create-message-app-cred.js
import {createClientWithAppCredentials} from './authentication-utils.js';

// This sample shows how to create message with app credential
async function main() {
  // Create a client
  const chatClient = createClientWithAppCredentials();

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    message: {
      text: '👋🌎 Hello world! I created this message by calling ' +
            'the Chat API\'s `messages.create()` method.',
      cardsV2 : [{ card: {
        header: {
          title: 'About this message',
          imageUrl: 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg'
        },
        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."
              }
            }]
          }
        ]
      }}],
      accessoryWidgets: [{ buttonList: { buttons: [{
        text: 'View documentation',
        icon: { materialIcon: { name: 'link' }},
        onClick: { openLink: {
          url: 'https://developers.google.com/workspace/chat/create-messages'
        }}
      }]}}]
    }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/create_message_app_cred.py
from authentication_utils import create_client_with_app_credentials
from google.apps import chat_v1 as google_chat

# This sample shows how to create message with app credential
def create_message_with_app_cred():
    # Create a client
    client = create_client_with_app_credentials()

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here.
        parent = "spaces/SPACE_NAME",
        message = {
            "text": '👋🌎 Hello world! I created this message by calling ' +
                    'the Chat API\'s `messages.create()` method.',
            "cards_v2" : [{ "card": {
                "header": {
                    "title": 'About this message',
                    "image_url": 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg'
                },
                "sections": [{
                    "header": "Contents",
                    "widgets": [{ "text_paragraph": {
                            "text": '🔡 <b>Text</b> which can include ' +
                                    'hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️.'
                        }}, { "text_paragraph": {
                            "text": '🖼️ A <b>card</b> to display visual elements' +
                                    'and request information such as text 🔤, ' +
                                    'dates and times 📅, and selections ☑️.'
                        }}, { "text_paragraph": {
                            "text": '👉🔘 An <b>accessory widget</b> which adds ' +
                                    'a button to the bottom of a message.'
                        }}
                    ]}, {
                        "header": "What's next",
                        "collapsible": True,
                        "widgets": [{ "text_paragraph": {
                                "text": "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>."
                            }}, { "text_paragraph": {
                                "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."
                            }
                        }]
                    }
                ]
            }}],
            "accessory_widgets": [{ "button_list": { "buttons": [{
                "text": 'View documentation',
                "icon": { "material_icon": { "name": 'link' }},
                "on_click": { "open_link": {
                    "url": 'https://developers.google.com/workspace/chat/create-messages'
                }}
            }]}}]
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_app_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageAppCred.java
import com.google.apps.card.v1.Button;
import com.google.apps.card.v1.ButtonList;
import com.google.apps.card.v1.Card;
import com.google.apps.card.v1.Icon;
import com.google.apps.card.v1.MaterialIcon;
import com.google.apps.card.v1.OnClick;
import com.google.apps.card.v1.OpenLink;
import com.google.apps.card.v1.TextParagraph;
import com.google.apps.card.v1.Widget;
import com.google.apps.card.v1.Card.CardHeader;
import com.google.apps.card.v1.Card.Section;
import com.google.chat.v1.AccessoryWidget;
import com.google.chat.v1.CardWithId;
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;

// This sample shows how to create message with app credential.
public class CreateMessageAppCred {

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithAppCredentials()) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        .setMessage(Message.newBuilder()
          .setText( "👋🌎 Hello world! I created this message by calling " +
                    "the Chat API\'s `messages.create()` method.")
          .addCardsV2(CardWithId.newBuilder().setCard(Card.newBuilder()
            .setHeader(CardHeader.newBuilder()
              .setTitle("About this message")
              .setImageUrl("https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg"))
            .addSections(Section.newBuilder()
              .setHeader("Contents")
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "🔡 <b>Text</b> which can include " +
                "hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️.")))
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "🖼️ A <b>card</b> to display visual elements " +
                "and request information such as text 🔤, " +
                "dates and times 📅, and selections ☑️.")))
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "👉🔘 An <b>accessory widget</b> which adds " +
                "a button to the bottom of a message."))))
            .addSections(Section.newBuilder()
              .setHeader("What's next")
              .setCollapsible(true)
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>.")))
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "🔄 <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."))))))
          .addAccessoryWidgets(AccessoryWidget.newBuilder()
            .setButtonList(ButtonList.newBuilder()
              .addButtons(Button.newBuilder()
                .setText("View documentation")
                .setIcon(Icon.newBuilder()
                  .setMaterialIcon(MaterialIcon.newBuilder().setName("link")))
                .setOnClick(OnClick.newBuilder()
                  .setOpenLink(OpenLink.newBuilder()
                    .setUrl("https://developers.google.com/workspace/chat/create-messages")))))));
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create message with app credential
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.bot'
 * used by service accounts.
 */
function createMessageAppCred() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const message = {
    text: '👋🌎 Hello world! I created this message by calling ' +
          'the Chat API\'s `messages.create()` method.',
    cardsV2 : [{ card: {
      header: {
        title: 'About this message',
        imageUrl: 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg'
      },
      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."
            }
          }]
        }
      ]
    }}],
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: 'View documentation',
      icon: { materialIcon: { name: 'link' }},
      onClick: { openLink: {
        url: 'https://developers.google.com/workspace/chat/create-messages'
      }}
    }]}}]
  };
  const parameters = {};

  // Make the request
  const response = Chat.Spaces.Messages.create(
    message, parent, parameters, getHeaderWithAppCredentials()
  );

  // Handle the response
  console.log(response);
}

Ersetzen Sie SPACE_NAME durch die ID aus dem Feld name des Arbeitsbereichs, um dieses Beispiel auszuführen. Sie können die ID abrufen, indem Sie die Methode ListSpaces() aufrufen oder die URL des Bereichs verwenden.

Interaktive Widgets unten in einer Nachricht hinzufügen

Im ersten Codebeispiel in dieser Anleitung wird in der Chat-App-Nachricht unten eine anklickbare Schaltfläche angezeigt, die als Zubehör-Widget bezeichnet wird. Zubehör-Widgets werden nach Text oder Karten in einer Nachricht angezeigt. Mit diesen Widgets können Sie Nutzer auf verschiedene Arten dazu auffordern, mit Ihrer Mitteilung zu interagieren, z. B. so:

  • Bewerten Sie die Richtigkeit oder Zufriedenheit einer Nachricht.
  • Problem mit der Nachricht oder der Chat App melden
  • Öffnen Sie einen Link zu zugehörigen Inhalten, z. B. Dokumentation.
  • Ähnliche Nachrichten aus der Chat App für einen bestimmten Zeitraum schließen oder in den Schlummermodus versetzen.

Wenn Sie Zubehör-Widgets hinzufügen möchten, fügen Sie das Feld accessoryWidgets[] in den Anfragetext ein und geben Sie ein oder mehrere Widgets an, die Sie einfügen möchten.

Das folgende Bild zeigt eine Chat-App, die einer Textnachricht Zubehör-Widgets hinzufügt, damit Nutzer ihre Erfahrungen mit der Chat-App bewerten können.

Zubehör-Widget
Abbildung 5: Eine Chat-App-Nachricht mit Text und Zubehör-Widgets.

Das Folgende zeigt den Text der Anfrage, mit der eine SMS mit zwei Zubehörschaltflächen erstellt wird. Wenn ein Nutzer auf eine Schaltfläche klickt, wird die entsprechende Funktion (z. B. doUpvote) aufgerufen, um die Interaktion zu verarbeiten:

{
  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"
    }}
  }]}}]
}

Private Nachrichten senden

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

Wenn Sie eine private Nachricht über die Chat API senden möchten, geben Sie das Feld privateMessageViewer im Hauptteil Ihrer Anfrage an. Um den Nutzer anzugeben, legen Sie den Wert auf die User-Ressource fest, die den Chat-Nutzer darstellt. Sie können auch das Feld name der Ressource User verwenden, wie im folgenden Beispiel gezeigt:

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

Wenn Sie dieses Beispiel verwenden möchten, ersetzen Sie USER_ID durch eine eindeutige 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.

Wenn Sie eine private Nachricht senden möchten, müssen Sie Folgendes in Ihrer Anfrage weglassen:

SMS im Namen eines Nutzers senden

In diesem Abschnitt wird erläutert, wie Sie mit Nutzerauthentifizierung Nachrichten im Namen eines Nutzers senden. Bei der Nutzerauthentifizierung darf der Inhalt der Nachricht nur Text enthalten. Messaging-Funktionen, die nur für Chat-Apps verfügbar sind, müssen weggelassen werden. Dazu gehören auch Kartenschnittstellen und interaktive Widgets.

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

Wenn Sie die Methode CreateMessage() mit Nutzerauthentifizierung aufrufen möchten, müssen Sie die folgenden Felder in der Anfrage angeben:

  • Ein Autorisierungsbereich, der die Nutzerauthentifizierung für diese Methode unterstützt. Im folgenden Beispiel wird der Bereich chat.messages.create verwendet.
  • Die Space-Ressource, in der Sie die Nachricht posten möchten. Der authentifizierte Nutzer muss Mitglied des Gruppenbereichs sein.
  • Die zu erstellende Message-Ressource. Um den Inhalt der Nachricht zu definieren, müssen Sie das Feld text angeben.

Optional können Sie Folgendes angeben:

  • Das Feld messageId, mit dem Sie die Nachricht benennen können, um sie in anderen API-Anfragen zu verwenden.
  • Die Felder thread.threadKey und messageReplyOption zum Starten oder Beantworten einer Unterhaltung. Wenn im Bereich keine Threads verwendet werden, wird dieses Feld ignoriert.

Der folgende Code zeigt ein Beispiel dafür, wie eine Chat-App im Namen eines authentifizierten Nutzers eine Textnachricht in einem bestimmten Gruppenbereich senden kann:

Node.js

chat/client-libraries/cloud/create-message-user-cred.js
import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.messages.create'];

// This sample shows how to create message with user credential
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    message: {
      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>.'
    }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/create_message_user_cred.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"]

def create_message_with_user_cred():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here.
        parent = "spaces/SPACE_NAME",
        message = {
            "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>.'
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_user_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageUserCred.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;

// This sample shows how to create message with user credential.
public class CreateMessageUserCred {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.messages.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        .setMessage(Message.newBuilder()
          .setText( "👋🌎 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>."));
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create message with user credential
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageUserCred() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const message = {
    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>.'
  };

  // Make the request
  const response = Chat.Spaces.Messages.create(message, parent);

  // Handle the response
  console.log(response);
}

Ersetzen Sie SPACE_NAME durch die ID aus dem Feld name des Arbeitsbereichs, um dieses Beispiel auszuführen. Sie können die ID abrufen, indem Sie die Methode ListSpaces() aufrufen oder die URL des Bereichs verwenden.

Unterhaltungsthread starten oder darauf antworten

Bei Gruppenbereichen mit Threads können Sie festlegen, ob mit einer neuen Nachricht ein Thread gestartet oder auf einen vorhandenen Thread geantwortet wird.

Standardmäßig wird mit Nachrichten, die Sie über die Chat API erstellen, ein neuer Thread gestartet. Damit Sie den Thread später leichter finden und darauf antworten können, können Sie in Ihrer Anfrage einen Thread-Schlüssel angeben:

  • Geben Sie im Text Ihrer Anfrage das Feld thread.threadKey an.
  • Geben Sie den Abfrageparameter messageReplyOption an, um festzulegen, was passieren soll, wenn der Schlüssel bereits vorhanden ist.

So erstellen Sie eine Nachricht, mit der auf einen vorhandenen Thread geantwortet wird:

  • Geben Sie im Anfragetext das Feld thread an. Falls festgelegt, können Sie die von Ihnen erstellte threadKey angeben. Andernfalls müssen Sie die name des Threads verwenden.
  • Geben Sie den Abfrageparameter messageReplyOption an.

Im folgenden Codebeispiel sehen Sie, wie eine Chat-App im Namen eines authentifizierten Nutzers eine SMS senden kann, mit der ein bestimmter Thread gestartet oder auf einen bestimmten Thread geantwortet wird, der durch den Schlüssel eines bestimmten Gruppenbereichs identifiziert wird:

Node.js

chat/client-libraries/cloud/create-message-user-cred-thread-key.js
import {createClientWithUserCredentials} from './authentication-utils.js';
const {MessageReplyOption} = require('@google-apps/chat').protos.google.chat.v1.CreateMessageRequest;

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.messages.create'];

// This sample shows how to create message with user credential with thread key
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    // Creates the message as a reply to the thread specified by thread_key
    // If it fails, the message starts a new thread instead
    messageReplyOption: MessageReplyOption.REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD,
    message: {
      text: 'Hello with user credential!',
      thread: {
        // Thread key specifies a thread and is unique to the chat app
        // that sets it
        threadKey: 'THREAD_KEY'
      }
    }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/create_message_user_cred_thread_key.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

import google.apps.chat_v1.CreateMessageRequest.MessageReplyOption

SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"]

# This sample shows how to create message with user credential with thread key
def create_message_with_user_cred_thread_key():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        # Creates the message as a reply to the thread specified by thread_key.
        # If it fails, the message starts a new thread instead.
        message_reply_option = MessageReplyOption.REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD,
        message = {
            "text": "Hello with user credential!",
            "thread": {
                # Thread key specifies a thread and is unique to the chat app
                # that sets it.
                "thread_key": "THREAD_KEY"
            }
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_user_cred_thread_key()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageUserCredThreadKey.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.CreateMessageRequest.MessageReplyOption;
import com.google.chat.v1.Message;
import com.google.chat.v1.Thread;

// This sample shows how to create message with a thread key with user
// credential.
public class CreateMessageUserCredThreadKey {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.messages.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        // Creates the message as a reply to the thread specified by thread_key.
        // If it fails, the message starts a new thread instead.
        .setMessageReplyOption(
          MessageReplyOption.REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD)
        .setMessage(Message.newBuilder()
          .setText("Hello with user credentials!")
          // Thread key specifies a thread and is unique to the chat app
          // that sets it.
          .setThread(Thread.newBuilder().setThreadKey("THREAD_KEY")));
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create message with user credential with thread key
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageUserCredThreadKey() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  // Creates the message as a reply to the thread specified by thread_key
  // If it fails, the message starts a new thread instead
  const messageReplyOption = 'REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD';
  const message = {
    text: 'Hello with user credential!',
    thread: {
      // Thread key specifies a thread and is unique to the chat app
      // that sets it
      threadKey: 'THREAD_KEY'
    }
  };

  // Make the request
  const response = Chat.Spaces.Messages.create(message, parent, {
    messageReplyOption: messageReplyOption
  });

  // Handle the response
  console.log(response);
}

Um dieses Beispiel auszuführen, ersetzen Sie Folgendes:

  • THREAD_KEY: Ein vorhandener Threads-Schlüssel im Bereich oder ein eindeutiger Name für den Thread, wenn ein neuer Thread erstellt werden soll.
  • SPACE_NAME: Die ID aus dem Feld name des Bereichs. Sie können die ID abrufen, indem Sie die Methode ListSpaces() aufrufen oder die URL des Bereichs verwenden.

Nachricht benennen

Wenn Sie eine Nachricht in zukünftigen API-Aufrufen abrufen oder angeben möchten, können Sie sie benennen, indem Sie das Feld messageId in Ihrer Anfrage festlegen. Wenn Sie Ihrer Nachricht einen Namen geben, können Sie sie angeben, ohne die vom System zugewiesene ID aus dem Ressourcennamen der Nachricht (im Feld name) speichern zu müssen.

Wenn Sie beispielsweise eine Nachricht mit der Methode get() abrufen möchten, geben Sie mit dem Ressourcennamen an, welche Nachricht abgerufen werden soll. Der Ressourcenname hat das Format spaces/{space}/messages/{message}, wobei {message} die vom System zugewiesene ID oder der benutzerdefinierte Name ist, den Sie beim Erstellen der Mitteilung festgelegt haben.

Wenn Sie einer Nachricht einen Namen geben möchten, geben Sie beim Erstellen der Nachricht eine benutzerdefinierte ID im Feld messageId an. Mit dem Feld messageId wird der Wert für das Feld clientAssignedMessageId der Ressource Message festgelegt.

Sie können eine Nachricht nur benennen, wenn Sie sie erstellen. Sie können keine benutzerdefinierte ID für vorhandene Nachrichten benennen oder ändern. Die benutzerdefinierte ID muss die folgenden Anforderungen erfüllen:

  • Beginnt mit client-. Beispiel: client-custom-name ist eine gültige benutzerdefinierte ID, custom-name jedoch nicht.
  • Enthält bis zu 63 Zeichen und nur Kleinbuchstaben, Ziffern und Bindestriche.
  • Sie ist innerhalb eines Bereichs eindeutig. Eine Chat-App kann nicht dieselbe benutzerdefinierte ID für verschiedene Nachrichten verwenden.

Der folgende Code zeigt ein Beispiel dafür, wie eine Chat-App im Namen eines authentifizierten Nutzers eine SMS mit einer ID an einen bestimmten Gruppenbereich senden kann:

Node.js

chat/client-libraries/cloud/create-message-user-cred-message-id.js
import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.messages.create'];

// This sample shows how to create message with user credential with message id
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    // Message id lets chat apps get, update or delete a message without needing
    // to store the system assigned ID in the message's resource name
    messageId: 'client-MESSAGE-ID',
    message: { text: 'Hello with user credential!' }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/create_message_user_cred_message_id.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"]

# This sample shows how to create message with user credential with message id
def create_message_with_user_cred_message_id():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        # Message id let chat apps get, update or delete a message without needing
        # to store the system assigned ID in the message's resource name.
        message_id = "client-MESSAGE-ID",
        message = {
            "text": "Hello with user credential!"
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_user_cred_message_id()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageUserCredMessageId.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;

// This sample shows how to create message with message id specified with user
// credential.
public class CreateMessageUserCredMessageId {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.messages.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        .setMessage(Message.newBuilder()
          .setText("Hello with user credentials!"))
        // Message ID lets chat apps get, update or delete a message without
        // needing to store the system assigned ID in the message's resource
        // name.
        .setMessageId("client-MESSAGE-ID");
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create message with user credential with message id
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageUserCredMessageId() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  // Message id lets chat apps get, update or delete a message without needing
  // to store the system assigned ID in the message's resource name
  const messageId = 'client-MESSAGE-ID';
  const message = { text: 'Hello with user credential!' };

  // Make the request
  const response = Chat.Spaces.Messages.create(message, parent, {
    messageId: messageId
  });

  // Handle the response
  console.log(response);
}

Um dieses Beispiel auszuführen, ersetzen Sie Folgendes:

  • SPACE_NAME: Die ID aus dem Feld name des Bereichs. Sie können die ID abrufen, indem Sie die Methode ListSpaces() aufrufen oder die URL des Bereichs verwenden.
  • MESSAGE-ID: ein Name für die Nachricht, die mit custom- beginnt. Muss sich von allen anderen Nachrichtennamen unterscheiden, die von der Chat-App im angegebenen Bereich erstellt wurden.

Fehlerbehebung

Wenn eine Google Chat-App oder Karte einen Fehler zurückgibt, wird in der Chat-Benutzeroberfläche die Meldung „Ein Fehler ist aufgetreten“ angezeigt. oder „Ihre Anfrage kann nicht bearbeitet werden.“ Manchmal wird in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt, aber die Chat-App oder ‑Karte liefert ein unerwartetes Ergebnis, z. B. wird eine Kartennachricht nicht angezeigt.

Auch wenn in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt wird, sind aussagekräftige Fehlermeldungen und Protokolldaten verfügbar, die Ihnen helfen, Fehler zu beheben, wenn die Fehlerprotokollierung für Chat-Apps aktiviert ist. Informationen zum Aufrufen, Debuggen und Beheben von Fehlern finden Sie unter Google Chat-Fehler beheben.