Gửi tin nhắn riêng tư cho người dùng Google Chat

Trang này giải thích cách tạo và gửi tin nhắn riêng tư dưới dạng ứng dụng Google Chat.

Tin nhắn riêng tư là thông báo trong ứng dụng Chat mà chỉ một người dùng cụ thể trong Chat mới nhìn thấy. Bạn có thể sử dụng tin nhắn riêng tư trong không gian có nhiều người để họ có thể tương tác riêng tư với các ứng dụng trong Chat. Ví dụ: ứng dụng Chat có thể gửi tin nhắn riêng tư để thực hiện bất kỳ việc nào sau đây:

  • Phản hồi lệnh dấu gạch chéo. Ví dụ: nếu người dùng gọi lệnh dấu gạch chéo /about của ứng dụng Chat trong một không gian, thì ứng dụng Chat đó có thể trả lời bằng một tin nhắn riêng tư giải thích chức năng của ứng dụng Chat và cách sử dụng tin nhắn đó.
  • Thông báo hoặc gửi thông tin chỉ liên quan đến một người dùng. Ví dụ: thông báo cho người dùng rằng họ đã được giao một nhiệm vụ hoặc nhắc họ hoàn thành một nhiệm vụ đó.
  • Gửi thông báo lỗi. Ví dụ: nếu người dùng bỏ qua văn bản đối số bắt buộc đối với lệnh dấu gạch chéo, ứng dụng Chat có thể gửi một tin nhắn riêng tư để giải thích lỗi và giúp người dùng định dạng lệnh đó.

Khi ứng dụng Chat gửi một tin nhắn riêng tư, tin nhắn đó sẽ hiện một nhãn để thông báo cho người dùng rằng tin nhắn đó chỉ hiển thị với họ:

Thông báo riêng tư của ứng dụng nhắn tin Cymbal Labs. Thông báo đó cho biết ứng dụng Chat do Cymbal Labs tạo ra và chia sẻ đường liên kết đến tài liệu cũng như đường liên kết để liên hệ với nhóm hỗ trợ.
Hình 1: Khi ứng dụng Chat gửi một tin nhắn riêng tư, người dùng sẽ thấy một tin nhắn có nhãn cho biết Only visible to you.

Điều kiện tiên quyết

Node.js

Lưu ý: Các mã mẫu Node.js trong hướng dẫn này được viết để chạy dưới dạng Hàm Google Cloud.

Python

Lưu ý: Các mã mẫu Python trong hướng dẫn này được viết để chạy dưới dạng Hàm Google Cloud sử dụng Python 3.10.

Apps Script

  • Một ứng dụng trong Chat. Để tạo một ứng dụng trong Chat, hãy làm theo phần quickstart này.
  • Để phản hồi riêng một lệnh dấu gạch chéo, một lệnh dấu gạch chéo được định cấu hình cho ứng dụng Chat. Để tạo một lệnh, hãy xem phần Phản hồi lệnh dấu gạch chéo.
  • Để gửi một tin nhắn riêng tư bằng phương thức messages.create(), bạn phải sử dụng tính năng xác thực ứng dụng.

Gửi tin nhắn riêng tư

Để gửi tin nhắn riêng tư dưới dạng ứng dụng Chat, bạn cần chỉ định trường privateMessageViewer trong thông báo khi tạo tin nhắn. Bạn tạo tin nhắn riêng tư giống như cách bạn tạo tin nhắn bất kỳ: bằng cách phản hồi hoạt động tương tác của người dùng hoặc gọi không đồng bộ phương thức create() của API Google Chat trên tài nguyên Message. Để biết các bước gửi tin nhắn văn bản hoặc thẻ, hãy xem phần Gửi tin nhắn.

Ví dụ sau đây cho thấy JSON cho một tin nhắn văn bản riêng tư có nội dung Hello private world!:

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

Trong ví dụ này, USER biểu thị người dùng Chat có thể xem tin nhắn ở định dạng tài nguyên User. Nếu phản hồi một lượt tương tác của người dùng, bạn có thể chỉ định đối tượng User từ sự kiện tương tác đó. Để biết ví dụ, hãy xem phần sau Phản hồi riêng tư lệnh dấu gạch chéo.

Nếu không, để chỉ định người xem nhận tin nhắn riêng tư, bạn có thể sử dụng trường name của tài nguyên User:

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

Trong ví dụ này, bạn sử dụng trường name để chỉ định tên tài nguyên User của người xem trong Google Chat. Thay thế USER_ID bằng một mã nhận dạng duy nhất cho người dùng, chẳng hạn như 12345678987654321 hoặc hao@cymbalgroup.com.

Để biết thêm thông tin về cách chỉ định người dùng, hãy xem phần Xác định và chỉ định người dùng Google Chat.

Phản hồi riêng tư lệnh dấu gạch chéo

Mã sau đây là ví dụ về một ứng dụng Chat phản hồi lệnh dấu gạch chéo kèm theo tin nhắn riêng tư.

Ứng dụng Chat xử lý một sự kiện tương tác MESSAGE và phản hồi lệnh dấu gạch chéo /help bằng một tin nhắn văn bản riêng tư giải thích cách sử dụng lệnh đó:

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

Các điểm hạn chế

Để gửi tin nhắn riêng tư, thư không được chứa hoặc sử dụng các nội dung sau:

  • Tệp đính kèm.
  • Thao tác với phụ kiện.
  • Tin nhắn riêng tư một phần. Ví dụ: ứng dụng Chat không thể gửi tin nhắn có văn bản và thẻ mà trong đó văn bản chỉ hiển thị cho một người dùng nhưng thẻ sẽ hiển thị cho tất cả mọi người trong không gian.
  • Xác thực người dùng. Chỉ các ứng dụng trong Chat mới có thể gửi tin nhắn riêng tư. Do đó, ứng dụng Chat không thể xác thực với tư cách người dùng để gửi tin nhắn riêng tư.

Cập nhật hoặc xoá tin nhắn riêng tư

Để cập nhật hoặc xoá tin nhắn trong Google Chat, bạn phải gọi API Chat. Bạn không thể thay đổi người xem tin nhắn riêng tư hoặc đặt tin nhắn ở chế độ công khai. Do đó, khi cập nhật thông báo riêng tư, bạn phải bỏ qua trường privateMessageViewer trong lệnh gọi API (trường này chỉ dành cho kết quả đầu ra).

Để cập nhật tin nhắn riêng tư, hãy xem phần Cập nhật tin nhắn. Để xoá tin nhắn riêng tư, hãy xem phần Xoá tin nhắn.