Отправляйте личные сообщения пользователям Google Chat

На этой странице объясняется, как создавать и отправлять личные сообщения в приложении Google Chat.

Личное сообщение — это сообщение приложения Chat, которое видно только определенному пользователю Chat. Вы можете использовать личные сообщения в группах с несколькими людьми, чтобы они могли конфиденциально взаимодействовать с приложениями чата. Например, ваше приложение Chat может конфиденциально отправлять сообщения для выполнения любого из следующих действий:

  • Ответить на команду косой черты . Например, если пользователь вызывает косую черту /about вашего приложения Chat в пространстве, ваше приложение Chat может ответить личным сообщением, в котором объясняется, что делает ваше приложение Chat и как его использовать.
  • Уведомляйте или отправляйте информацию, которая относится только к одному пользователю. Например, уведомите пользователя о том, что ему назначена задача, или напомните ему о необходимости выполнить задачу.
  • Отправьте сообщение об ошибке. Например, если пользователь опускает обязательный текст аргумента для команды с косой чертой, приложение Chat может отправить личное сообщение с объяснением ошибки и помочь пользователю отформатировать команду.

Когда приложение чата отправляет личное сообщение, в сообщении отображается метка, уведомляющая пользователя о том, что сообщение видно только ему:

Личное сообщение для приложения Cymbal Labs Chat. В сообщении говорится, что приложение Chat было создано Cymbal Labs, и содержится ссылка на документацию и ссылку для связи со службой поддержки.
Рис. 1. Когда приложение чата отправляет личное сообщение, пользователь видит сообщение с меткой « Only visible to you .

Предварительные условия

Node.js

Примечание. Примеры кода Node.js в этом руководстве написаны для запуска как функция Google Cloud .

Питон

Примечание. Примеры кода Python в этом руководстве написаны для запуска как функция Google Cloud с использованием Python 3.10.

Скрипт приложений

Отправить личное сообщение

Чтобы отправить сообщение конфиденциально как приложение чата, вы указываете поле privateMessageViewer в сообщении при его создании. Вы создаете личные сообщения так же, как и любое сообщение: либо отвечая на взаимодействие с пользователем, либо асинхронно вызывая метод create() API чата Google для ресурса Message . Инструкции по отправке текстовых сообщений или карточек см. в разделе «Отправка сообщения» .

В следующем примере показан JSON для частного текстового сообщения с надписью Hello private world! :

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

В этом примере USER представляет пользователя чата, который может просматривать сообщение, отформатированное как ресурс User . Если вы отвечаете на взаимодействие с пользователем, вы можете указать объект User из события взаимодействия. Пример см. в следующем разделе «Ответ на косую черту в частном порядке ».

В противном случае, чтобы указать зрителя для личного сообщения, вы можете использовать поле name ресурса User :

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

В этом примере вы используете поле name , чтобы указать имя ресурса User зрителя в Google Chat. Замените USER_ID уникальным идентификатором пользователя, например 12345678987654321 или hao@cymbalgroup.com .

Дополнительную информацию об указании пользователей см. в разделе Идентификация и указание пользователей Google Chat .

Ответить лично на команду косой черты

В следующем коде показан пример приложения Chat, которое отвечает на команду косой черты личным сообщением.

Приложение Chat обрабатывает событие взаимодействия MESSAGE и отвечает на команду /help косой чертой личным текстовым сообщением, в котором объясняется, как ее использовать:

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

Скрипт приложений

/**
* 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 };
  }
}

Питон

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

Ограничения

Чтобы отправить личное сообщение, сообщение не может содержать или использовать следующее:

  • Вложения .
  • Вспомогательные действия .
  • Частично-приватные сообщения. Например, приложение чата не может отправить сообщение с текстом и карточкой, где текст виден только одному пользователю, а карточка видна всем в пространстве.
  • Аутентификация пользователя . Только приложения чата могут отправлять личные сообщения, поэтому ваше приложение чата не может пройти аутентификацию в качестве пользователя для отправки личного сообщения.

Обновить или удалить личные сообщения

Чтобы обновить или удалить сообщения Google Chat, вам необходимо вызвать Chat API. Вы не можете изменить зрителя личного сообщения или сделать сообщение общедоступным. Поэтому при обновлении личных сообщений необходимо опустить поле privateMessageViewer в вызове API (поле предназначено только для вывода).

Чтобы обновить личное сообщение, см. Обновление сообщения . Чтобы удалить личное сообщение, см. раздел Удаление сообщения .