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à tin nhắn trong ứng dụng Chat chỉ hiển thị với người dùng Chat cụ thể. Bạn có thể sử dụng tin nhắn riêng tư trong không gian với nhiều người để họ có thể tương tác riêng tư Ứng dụng nhắn tin. Ví dụ: Ứng dụng Chat có thể gửi tin nhắn một cách riêng tư để thực hiện bất kỳ việc nào sau:

  • Phản hồi lệnh dấu gạch chéo. Ví dụ: nếu người dùng gọi dấu gạch chéo /about của ứng dụng Chat trong một không gian, ứ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 tính năng và cách sử dụng chúng.
  • 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 việc cần làm hoặc nhắc họ để hoàn thành 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 để giải thích lỗi và giúp người dùng định dạng lệnh.
  • Gửi tin nhắn chào mừng riêng tư cho người dùng khi họ được thêm vào không gian giải thích các nguyên tắc hoặc cách dùng ứng dụng Chat.

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

Thư cá nhân cho
  Ứng dụng Cymbal Labs trong Chat. Thông báo cho biết
  Ứng dụng nhắn tin do Cymbal Labs tạo và chia sẻ một đường liên kết
  tài liệu và đườ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 thư riêng tư, người dùng sẽ thấy thư có nhãn có nội dung Only visible to you.

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

Node.js

  • Một ứng dụng Google Chat đã bật các tính năng tương tác. Để tạo một ứng dụng Chat tương tác bằng dịch vụ HTTP, hãy hoàn thành phần bắt đầu nhanh này.
  • Để phản hồi riêng một lệnh dấu gạch chéo, lệnh dấu gạch chéo được định cấu hình cho ứng dụng Chat. Để tạo một ứng dụng, hãy xem Phản hồi các lệnh dấu gạch chéo.

  • Để gửi tin nhắn riêng tư bằng messages.create() bạn phải sử dụng xác thực ứng dụng.

Python

  • Một ứng dụng Google Chat đã bật các tính năng tương tác. Để tạo một ứng dụng Chat tương tác bằng dịch vụ HTTP, hãy hoàn thành phần bắt đầu nhanh này.
  • Để phản hồi riêng một lệnh dấu gạch chéo, lệnh dấu gạch chéo được định cấu hình cho ứng dụng Chat. Để tạo một ứng dụng, hãy xem Phản hồi các lệnh dấu gạch chéo.

  • Để gửi tin nhắn riêng tư bằng messages.create() bạn phải sử dụng xác thực ứng dụng.

Apps Script

  • Một ứng dụng Google Chat đã bật các tính năng tương tác. Để tạo một ứng dụng Chat tương tác trong Apps Script, hãy hoàn thành phần bắt đầu nhanh này.
  • Để phản hồi riêng một lệnh dấu gạch chéo, lệnh dấu gạch chéo được định cấu hình cho ứng dụng Chat. Để tạo một ứng dụng, hãy xem Phản hồi các lệnh dấu gạch chéo.

  • Để gửi tin nhắn riêng tư bằng messages.create() bạn phải sử dụng xác thực ứng dụng.

Gửi thông báo riêng

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

Ví dụ sau đây cho thấy JSON của 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 đại diện cho người dùng Chat người có thể xem thư, được định dạng là Tài nguyên User. Nếu phản hồi lạ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 đây Phản hồi riêng tư với lệnh dấu gạch chéo.

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

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

Trong ví dụ này, bạn sử dụng trường name để chỉ định User của người xem tên tài nguyên trong Google Chat. Thay thế USER_ID có 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ề việc chỉ định người dùng, hãy xem Xác định và chỉ định người dùng Google Chat.

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

Đoạn 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 với thông báo riêng tư.

Ứng dụng Chat sẽ xử lý một MESSAGE sự kiện tương tác và trả lờ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:

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ư, tin nhắn không được chứa hoặc sử dụng sau:

  • Tệp đính kèm.
  • Thao tác đối 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à một thẻ mà chỉ hiển thị văn bản với một người dùng nhưng thẻ sẽ hiển thị với 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 là 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 thông báo công khai. Do đó, khi cập nhật tin nhắn riêng tư, bạn phải bỏ qua trường privateMessageViewer trong lệnh gọi API (chỉ trường đầu ra).

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