Private Nachrichten an Google Chat-Nutzer senden

Auf dieser Seite wird erläutert, wie Sie private Nachrichten als Google Chat-App erstellen und senden.

Eine private Nachricht ist eine Nachricht in einer Chat-App, die nur für einen bestimmten Chat-Nutzer sichtbar ist. Sie können private Nachrichten in Gruppenbereichen mit mehreren Personen verwenden, damit diese privat mit Chat-Apps interagieren können. Ihre Chat-App kann beispielsweise privat Nachrichten senden, um Folgendes zu tun:

  • Auf einen Slash-Befehl reagieren. Wenn ein Nutzer beispielsweise den Slash-Befehl /about Ihrer Chat-App in einem Gruppenbereich aufruft, kann die Chat-App mit einer privaten Nachricht antworten, in der erläutert wird, was die Chat-App tut und wie sie verwendet wird.
  • Informationen benachrichtigen oder senden, die nur für einen Nutzer relevant sind. Sie können beispielsweise einen Nutzer darüber informieren, dass ihm eine Aufgabe zugewiesen wurde, oder ihn daran erinnern, die Aufgabe abzuschließen.
  • Fehlermeldung senden Wenn ein Nutzer beispielsweise den erforderlichen Argumenttext für einen Slash-Befehl auslässt, kann die Chat-Anwendung eine private Nachricht senden, um den Fehler zu erklären und dem Nutzer beim Formatieren des Befehls zu helfen.

Wenn eine Chat-App eine private Nachricht sendet, wird dem Nutzer ein Label mit dem Hinweis angezeigt, dass die Nachricht nur für ihn sichtbar ist:

Private Nachricht für die Chat-App von Cymbal Labs. Darin wird angegeben, dass die Chat-App von Cymbal Labs erstellt wurde. Sie enthält einen Link zur Dokumentation und einen Link zur Kontaktaufnahme mit dem Supportteam.
Abbildung 1: Wenn eine Chat-App eine private Nachricht sendet, sieht der Nutzer eine Nachricht mit dem Label Only visible to you.

Voraussetzungen

Node.js

  • Ein Google Cloud-Projekt, in dem die Google Chat API aktiviert und konfiguriert ist. Eine entsprechende Anleitung finden Sie unter Google Chat-App erstellen.
  • Für die private Antwort auf einen Slash-Befehl ist dies ein Slash-Befehl, der für die Chat-App konfiguriert ist. Informationen zum Erstellen eines Slash-Befehls finden Sie unter Auf Slash-Befehle antworten.
  • Zum Senden einer privaten Nachricht mit der Methode messages.create() müssen Sie die App-Authentifizierung verwenden.

Hinweis:Die Node.js-Codebeispiele in diesem Leitfaden wurden zur Ausführung als Google Cloud Functions-Funktion geschrieben.

Python

  • Ein Google Cloud-Projekt, in dem die Google Chat API aktiviert und konfiguriert ist. Eine entsprechende Anleitung finden Sie unter Google Chat-App erstellen.
  • Für die private Antwort auf einen Slash-Befehl ist dies ein Slash-Befehl, der für die Chat-App konfiguriert ist. Informationen zum Erstellen eines Slash-Befehls finden Sie unter Auf Slash-Befehle antworten.
  • Zum Senden einer privaten Nachricht mit der Methode messages.create() müssen Sie die App-Authentifizierung verwenden.

Hinweis:Die Python-Codebeispiele in diesem Leitfaden wurden zur Ausführung als Google Cloud Functions-Funktion mit Python 3.10 geschrieben.

Apps Script

  • Eine Chat-App. Informationen zum Erstellen einer Chat-App finden Sie in dieser quickstart.
  • Für die private Antwort auf einen Slash-Befehl ist dies ein Slash-Befehl, der für die Chat-App konfiguriert ist. Informationen zum Erstellen eines Slash-Befehls finden Sie unter Auf Slash-Befehle antworten.
  • Zum Senden einer privaten Nachricht mit der Methode messages.create() müssen Sie die App-Authentifizierung verwenden.

Du kannst jetzt eine private Nachricht senden

Wenn Sie eine Nachricht privat als Chat-App senden möchten, geben Sie beim Erstellen das Feld privateMessageViewer in der Nachricht an. Private Nachrichten werden genauso erstellt wie jede andere Nachricht: Sie können entweder auf eine Nutzerinteraktion antworten oder die Methode create() der Google Chat API asynchron für die Ressource Message aufrufen. Schritte zum Senden von Text- oder Kartennachrichten findest du unter Nachricht senden.

Das folgende Beispiel zeigt das JSON-Format für eine private Textnachricht mit dem Text Hello private world!:

{
    "text": "Hello private world!",
    "privateMessageViewer": "USER"
}

In diesem Beispiel stellt USER den Chat-Nutzer dar, der die Nachricht im Format User ansehen kann. Für die Reaktion auf eine Nutzerinteraktion können Sie das User-Objekt aus dem Interaktionsereignis angeben. Ein Beispiel finden Sie im folgenden Abschnitt Privat auf einen Slash-Befehl antworten.

Alternativ können Sie das Feld name der Ressource User verwenden, um den Betrachter für eine private Nachricht anzugeben:

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

In diesem Beispiel verwenden Sie das Feld name, um den User-Ressourcennamen des Betrachters in Google Chat anzugeben. 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 spezifizieren.

Privat auf einen Slash-Befehl antworten

Der folgende Code zeigt ein Beispiel für eine Chat-App, die auf einen Slash-Befehl mit einer privaten Nachricht reagiert.

Die Chat-App verarbeitet ein MESSAGE-Interaktionsereignis und antwortet auf den Slash-Befehl /help mit einer privaten Textnachricht, in der die Verwendung erklärt wird:

Node.js 

/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {!Object} req Request sent from Google Chat app
* @param {!Object} res Response to send back
*
* @return {!Object} respond to slash command
*/
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    return res.send('Hello! This function is meant to be used in Google Chat app.');
  }

  const event = req.body;

  // Checks for the presence of event.message.slashCommand.
  // If the slash command is "/help", responds with a private text message.
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case '1':  // /help
        return res.json({
          privateMessageViewer: event.user,
          text: 'This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>.'
        });
    }
  }

  // If the Chat app doesn't detect a slash command, it responds
  // with a private text message
  return res.json({
    privateMessageViewer: event.user,
    text: 'Try a slash command.'
  });
};

Apps Script 

/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onMessage(event) {
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case 1: // Responds to /help
        return {
          "privateMessageViewer": event.user,
          "text": "This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>."
        };
    }
  }
  else {
    return { "text": "Try a slash command.", "privateMessageViewer": event.user };
  }
}

Python 

from typing import Any, Mapping

import flask
import functions_framework

@functions_framework.http
def main(req: flask.Request) -> Mapping[str, Any]:
  """Responds to a MESSAGE event in Google Chat.

  Args:
      req (flask.Request): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """
  if req.method == 'GET':
    return 'Hello! This function must be called from Google Chat.'

  request = req.get_json(silent=True)

  # Checks for the presence of event.message.slashCommand.
  # If the slash command is "/help", responds with a private text message.
  if request.get('message', {}).get('slashCommand'):
    command_id = request.get('message', {}).get('slashCommand').get('commandId')
    if command_id == '1':  # /help
      return {
          'privateMessageViewer': request.get('user'),
          'text': (
              'This Chat app was created by Cymbal Labs. To get help with this'
              ' app, <https://cymbalgroup.com/docs|see our documentation> or'
              ' <https://cymbalgroup.com/support|contact our support team>.'
          ),
      }

  return {
      'privateMessageViewer': request.get('user'),
      'text': 'Try a slash command.',
  }

Beschränkungen

Eine private Nachricht darf Folgendes nicht enthalten oder verwenden:

  • Anhänge.
  • Aktionen für Zubehör:
  • Teilweise private Nachrichten. Eine Chat-App kann beispielsweise keine Nachricht mit Text und einer Karte senden, bei der der Text nur für einen Nutzer, die Karte aber für alle im Gruppenbereich sichtbar ist.
  • Nutzerauthentifizierung: Nur Chat-Apps können private Nachrichten senden. Daher kann sich die Chat-Anwendung nicht als Nutzer authentifizieren, um eine Nachricht privat zu senden.

Private Nachrichten aktualisieren oder löschen

Wenn Sie Google Chat-Nachrichten aktualisieren oder löschen möchten, müssen Sie die Chat API aufrufen. Sie können den Betrachter der privaten Nachricht nicht ändern oder die Nachricht öffentlich machen. Wenn Sie private Nachrichten aktualisieren, müssen Sie daher das Feld privateMessageViewer im API-Aufruf weglassen (das Feld wird nur ausgegeben).

Informationen zum Aktualisieren einer privaten Nachricht finden Sie unter Nachricht aktualisieren. Informationen zum Löschen einer privaten Nachricht findest du unter Nachricht löschen.