Nachricht über die Google Chat API senden

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

  • Nachrichten mit Text, Karten und interaktiven Widgets senden
  • Sie können Nachrichten privat an einen bestimmten Google Chat-Nutzer senden.
  • Eine Unterhaltung starten oder auf eine Unterhaltung 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. So kann beispielsweise eine Willkommensnachricht gepostet werden, 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, z. B. interaktive Dialoge und Linkvorschauoberflächen. Wenn Sie einem Nutzer antworten, gibt die Chat-App die Nachricht synchron zurück, ohne die Chat API aufzurufen. Informationen zum Senden von Nachrichten, um auf Interaktionen zu reagieren, finden Sie unter Interaktionen mit der Google Chat App empfangen und darauf antworten.

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

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

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

Methode „create()“ mit App-Authentifizierung aufrufen
Abbildung 1: Bei der App-Authentifizierung sendet die Chat-App die Nachricht. Wenn der Absender keine Person ist, wird in Google Chat neben dem Namen das Symbol App angezeigt.

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

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

Der Authentifizierungstyp bestimmt auch, welche Messaging-Funktionen und ‑oberflächen Sie in die Nachricht aufnehmen können. Mit der App-Authentifizierung können Chat-Apps Nachrichten mit Rich-Text, kartenbasierten Benutzeroberflächen und interaktiven Widgets senden. Da Chat-Nutzer nur Textnachrichten senden können, können Sie nur dann Text eingeben, wenn Sie Nachrichten mit Nutzerauthentifizierung erstellen. 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 beschrieben, wie Sie mit beiden Authentifizierungstypen eine Nachricht mit der Chat API senden.

Vorbereitung

Node.js

Python

Java

Apps Script

Nachrichten als Chat-App senden

In diesem Abschnitt wird beschrieben, wie Sie Nachrichten mit Text, Karten und interaktiven Widget-Zubehörteilen mithilfe der App-Authentifizierung senden.

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

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

  • Der chat.bot-Autorisierungsbereich.
  • Die Space-Ressource, in der Sie die Nachricht posten möchten. Die Chat-App muss Mitglied des Gruppenbereichs sein.
  • Die zu erstellende Message-Ressource. Sie können den Inhalt der Nachricht mithilfe von Rich Text (text), einer oder mehreren Kartenoberflächen (cardsV2) oder einer Kombination aus beiden definieren.

Optional können Sie Folgendes angeben:

Im folgenden Codebeispiel wird gezeigt, wie eine Chat-App eine Nachricht senden kann, die als Chat-App gepostet wird und Text, eine Karte und eine anklickbare Schaltfläche unten in 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);
}

Wenn Sie dieses Beispiel ausführen möchten, ersetzen Sie SPACE_NAME durch die ID aus dem Feld name des Gruppenbereichs. Sie können die ID durch Aufrufen der Methode ListSpaces() oder aus der URL des Gruppenbereichs abrufen.

Interaktive Widgets unten in einer Nachricht hinzufügen

Im ersten Codebeispiel dieses Leitfadens wird in der Chat-App-Nachricht unten eine anklickbare Schaltfläche angezeigt, die als Zubehör-Widget bezeichnet wird. Widget für Zubehör wird 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.:

  • Bewerten Sie die Richtigkeit oder Zufriedenheit mit einer Nachricht.
  • Problem mit der Nachrichten- oder Chat-App melden
  • Öffnen Sie einen Link zu ähnlichen Inhalten, z. B. zu einer Dokumentation.
  • Sie können ähnliche Nachrichten in der Chat App für einen bestimmten Zeitraum schließen oder pausieren.

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 einschließen möchten.

Das folgende Bild zeigt eine Chat-App, in der einer Nachricht zusätzliche Widgets angehängt werden, damit Nutzer ihre Erfahrungen mit der Chat-App bewerten können.

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

Im Folgenden sehen Sie den Text der Anfrage, mit der eine SMS mit zwei Zusatzschaltflächen erstellt wird. Wenn ein Nutzer auf eine Schaltfläche klickt, verarbeitet die entsprechende Funktion (z. B. doUpvote) die Interaktion:

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

Mit Chat-Apps können Nachrichten privat gesendet werden, sodass sie nur für einen bestimmten Nutzer im Gruppenbereich sichtbar sind. 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 Nachricht privat über die Chat API senden möchten, geben Sie das Feld privateMessageViewer im Textkörper Ihrer Anfrage an. Um den Nutzer anzugeben, legen Sie den Wert auf die User-Ressource fest, die den Google 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 Nachricht privat 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 mithilfe der Nutzerauthentifizierung Nachrichten im Namen eines Nutzers senden. Bei der Nutzerauthentifizierung darf der Inhalt der Nachricht nur Text enthalten und es dürfen keine Nachrichtenfunktionen verwendet werden, die nur für Chat-Apps verfügbar sind, z. B. Kartenoberflächen und interaktive Widgets.

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

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

  • Einen Autorisierungsbereich, der die Nutzerauthentifizierung für diese Methode unterstützt. Im folgenden Beispiel wird der chat.messages.create-Bereich 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:

Im folgenden Code wird gezeigt, wie eine Chat-App im Namen eines authentifizierten Nutzers eine Nachricht 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);
}

Wenn Sie dieses Beispiel ausführen möchten, ersetzen Sie SPACE_NAME durch die ID aus dem Feld name des Gruppenbereichs. Sie können die ID durch Aufrufen der Methode ListSpaces() oder aus der URL des Gruppenbereichs abrufen.

Unterhaltungen starten oder in Unterhaltungen antworten

Bei Gruppenbereichen, in denen Threads verwendet werden, können Sie festlegen, ob eine neue Nachricht einen Thread startet oder auf einen vorhandenen Thread antwortet.

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

  • Geben Sie im Anfragetext 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, die auf einen vorhandenen Thread antwortet:

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

Im folgenden Codebeispiel wird gezeigt, wie eine Chat-App im Namen eines authentifizierten Nutzers eine SMS senden kann, die einen bestimmten Thread startet oder auf einen bestimmten Thread antwortet, 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);
}

Ersetzen Sie zum Ausführen dieses Beispiels Folgendes:

  • THREAD_KEY: ein vorhandener Thread-Schlüssel im Gruppenbereich oder ein eindeutiger Name für einen neuen Thread.
  • SPACE_NAME: die ID aus dem Feld name des Gruppenbereichs. Sie können die ID durch Aufrufen der Methode ListSpaces() oder aus der URL des Gruppenbereichs abrufen.

Nachrichten einen Namen geben

Wenn Sie eine Nachricht in zukünftigen API-Aufrufen abrufen oder angeben möchten, können Sie ihr einen Namen geben, indem Sie das Feld messageId in Ihrer Anfrage festlegen. Wenn Sie eine Nachricht benennen, können Sie sie angeben, ohne die vom System zugewiesene ID aus dem Ressourcennamen der Nachricht (im Feld name dargestellt) 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} für die vom System zugewiesene ID oder den benutzerdefinierten Namen steht, den Sie beim Erstellen der Nachricht festgelegt haben.

Wenn Sie eine Nachricht benennen 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 beim Erstellen benennen. Sie können eine benutzerdefinierte ID für vorhandene Nachrichten nicht 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.
  • Darf innerhalb eines Gruppenbereichs nur einmal vorkommen. Eine Chat-App kann nicht dieselbe benutzerdefinierte ID für verschiedene Nachrichten verwenden.

Im folgenden Codebeispiel wird gezeigt, 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);
}

Ersetzen Sie zum Ausführen dieses Beispiels Folgendes:

  • SPACE_NAME: die ID aus dem Feld name des Gruppenbereichs. Sie können die ID durch Aufrufen der Methode ListSpaces() oder aus der URL des Gruppenbereichs abrufen.
  • MESSAGE-ID: ein Name für die Nachricht, der mit custom- beginnt. Der Name darf nicht mit dem Namen einer anderen Nachricht übereinstimmen, die in der Chat-App im angegebenen Gruppenbereich erstellt wurde.

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 konnte nicht verarbeitet werden“ Manchmal wird in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt, aber die Chat-App oder -Karte führt zu einem unerwarteten Ergebnis. Beispielsweise wird möglicherweise keine Kartennachricht angezeigt.

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