Wysyłanie wiadomości prywatnych do użytkowników Google Chat

Z tego artykułu dowiesz się, jak tworzyć i wysyłać wiadomości prywatne w aplikacji Google Chat.

Wiadomość prywatna to wiadomość w aplikacji Google Chat, która jest widoczna tylko dla określonego użytkownika tej usługi. Wiadomości prywatnych w pokojach z wieloma osobami możesz używać w pokojach, aby umożliwić im prywatne interakcje z aplikacjami Google Chat. Na przykład aplikacja Google Chat może wysyłać prywatnie wiadomości w tych celach:

  • Odpowiedz na polecenie po ukośniku. Jeśli na przykład użytkownik wywoła w pokoju polecenie /about z Twojej aplikacji do obsługi czatu, ta aplikacja może wysłać w odpowiedzi wiadomość prywatną z opisem działania aplikacji do obsługi czatu i jej używania.
  • Możesz powiadamiać i wysyłać informacje, które są istotne tylko dla jednego użytkownika. Możesz na przykład powiadomić użytkownika, że przypisano mu zadanie, lub przypomnieć mu o jego ukończeniu.
  • Wyślij komunikat o błędzie. Jeśli na przykład użytkownik pominie wymagany tekst argumentu w poleceniu po ukośniku, aplikacja Google Chat może wysłać prywatną wiadomość z wyjaśnieniem błędu i pomocną w sformatowaniu polecenia.

Gdy aplikacja do obsługi czatu wysyła wiadomość prywatną, wyświetla się w niej etykieta informująca użytkownika, że wiadomość jest widoczna tylko dla niego:

Prywatna wiadomość dla aplikacji Cymbal Labs Chat. Komunikat zawiera informację, że aplikacja Google Chat została utworzona przez Cymbal Labs i zawiera link do dokumentacji oraz link do kontaktu z zespołem pomocy.
Rysunek 1. Gdy aplikacja Google Chat wysyła wiadomość prywatną, użytkownik widzi wiadomość z etykietą Only visible to you.

Wymagania wstępne

Node.js

Uwaga: przykładowy kod w Node.js w tym przewodniku został przygotowany do uruchamiania jako funkcji w Google Cloud Functions.

Python

Uwaga: przykładowy kod w Pythonie w tym przewodniku został opracowany tak, aby uruchamiał się jako funkcja w Google Cloud Functions z użyciem języka Python 3.10.

Google Apps Script

Wyślij wiadomość prywatną

Aby wysłać wiadomość prywatnie jako aplikację Google Chat, podczas tworzenia wiadomości określ w niej pole privateMessageViewer. Wiadomości prywatne tworzy się tak samo jak każdą wiadomość: odpowiadają na interakcję użytkownika lub asynchronicznie wywołując metodę create() interfejsu Google Chat API z użyciem zasobu Message. Instrukcje wysyłania SMS-ów i kartek znajdziesz w artykule Wysyłanie wiadomości.

Ten przykład pokazuje kod JSON prywatnej wiadomości tekstowej Hello private world!:

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

W tym przykładzie USER reprezentuje użytkownika Google Chat, który może wyświetlić wiadomość, w formacie zasobu User. Jeśli odpowiadasz na interakcję użytkownika, możesz określić obiekt User ze zdarzenia interakcji. Przykład znajduje się w sekcji Odpowiadanie prywatnie na polecenie po ukośniku.

Aby określić przeglądającego wiadomość prywatną, możesz użyć pola name zasobu User:

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

W tym przykładzie użyjesz pola name, aby określić nazwę zasobu User wyświetlającego w Google Chat. Zastąp USER_ID unikalnym identyfikatorem użytkownika, takim jak 12345678987654321 lub hao@cymbalgroup.com.

Więcej informacji na temat określania użytkowników znajdziesz w artykule Identyfikowanie i określanie użytkowników Google Chat.

Odpowiadanie prywatnie na polecenie po ukośniku

Poniższy kod pokazuje przykład aplikacji Google Chat, która odpowiada na polecenie po ukośniku w wiadomości prywatnej.

Aplikacja Google Chat przetwarza zdarzenie interakcji MESSAGE i odpowiada na polecenie po ukośniku /help, wysyłając prywatnego SMS-a z wyjaśnieniem, jak z niego korzystać:

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.'
  });
};

Google 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.',
  }

Ograniczenia

Wysyłanie wiadomości prywatnej nie może zawierać następujących elementów:

  • Załączniki.
  • Działania związane z akcesoriami.
  • Wiadomości częściowo prywatne. Na przykład aplikacja Google Chat nie może wysłać wiadomości z tekstem i karty, gdy tekst jest widoczny tylko dla jednego użytkownika, ale karta jest widoczna dla wszystkich osób w pokoju.
  • Uwierzytelnianie użytkowników. Tylko aplikacje do obsługi czatu mogą wysyłać wiadomości prywatne, więc aplikacja ta nie może uwierzytelnić się jako użytkownik, aby wysyłać prywatne wiadomości.

Aktualizowanie i usuwanie wiadomości prywatnych

Aby zaktualizować lub usunąć wiadomości w Google Chat, musisz wywołać interfejs Chat API. Nie możesz zmienić przeglądającego wiadomości prywatnej ani upublicznić wiadomości. Dlatego gdy aktualizujesz wiadomości prywatne, musisz w wywołaniu interfejsu API pominąć pole privateMessageViewer (to pole zawiera tylko dane wyjściowe).

Aby zaktualizować wiadomość prywatną, zobacz Aktualizowanie wiadomości. Aby dowiedzieć się, jak usunąć wiadomość prywatną, przeczytaj sekcję Usuwanie wiadomości.