傳送私人訊息給 Google Chat 使用者

本頁面說明如何以 Google Chat 應用程式的形式建立及傳送私人訊息。

私人訊息是 Chat 應用程式訊息，只有特定 Chat 使用者能看得見。您可以在聊天室中與多人使用私人訊息，讓他們與 Chat 應用程式進行私密互動。舉例來說，Chat 應用程式可透過私密方式傳送訊息，以執行下列任一操作：

  • 回應斜線指令。舉例來說，如果使用者在聊天室中叫用 Chat 應用程式的 /about 斜線指令，您的 Chat 應用程式就能以私人訊息回覆，說明 Chat 應用程式的用途和使用方式。
  • 僅通知或傳送只與一位使用者相關的資訊。例如，通知使用者已獲派工作，或提醒他們完成工作。
  • 傳送錯誤訊息。舉例來說，如果使用者省略斜線指令的必要引數文字，Chat 應用程式就會傳送私人訊息，藉此說明錯誤內容，並協助使用者設定指令的格式。

當 Chat 應用程式傳送私人訊息時，訊息會顯示標籤，通知使用者該訊息僅供檢視：

Cymbal Labs 的即時通訊應用程式私人訊息。訊息內容顯示 Chat 應用程式是由 Cymbal Labs 所建立，並提供了說明文件連結和與支援團隊聯絡的連結。
圖 1：即時通訊應用程式傳送私人訊息時，使用者會看到含有 Only visible to you 標籤的訊息。

必要條件

Node.js

注意事項：本指南中的 Node.js 程式碼範例都已編寫為 Google Cloud 函式執行。

Python

注意事項：本指南中的 Python 程式碼範例是使用 Python 3.10，以 Google Cloud 函式的形式編寫而成。

Apps Script

  • 即時通訊應用程式。如要建構 Chat 應用程式，請按照這個quickstart操作。
  • 如要私下回應斜線指令，請為 Chat 應用程式設定的斜線指令。如要建構斜線指令，請參閱回應斜線指令。
  • 如要使用 messages.create() 方法傳送私人訊息，您必須使用應用程式驗證。

傳送私人訊息

如要以 Chat 應用程式的形式傳送私人訊息，請在建立訊息時指定 privateMessageViewer 欄位。建立私人訊息的方式與建立任何訊息相同：回應使用者互動，或在 Message 資源上以非同步方式呼叫 Google Chat API 的 create() 方法。如需傳送簡訊或資訊卡訊息的步驟，請參閱「傳送訊息」一節。

以下範例顯示 Hello private world! 私人文字訊息的 JSON：

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

在這個範例中，USER 代表可以查看訊息的 Chat 使用者，其格式為 User。如果回應使用者互動，可以在互動事件中指定 User 物件。如需範例，請參閱下方的「私下回應斜線指令」一節。

否則，您可以使用 User 資源的 name 欄位來指定私人訊息的檢視器：

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

在此範例中，您將使用 name 欄位指定 Google Chat 中檢視者的 User 資源名稱。將 USER_ID 替換為使用者的專屬 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.'
  });
};

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

限制

如要傳送私人訊息，訊息中不得包含或使用以下內容：

  • 附件。
  • 配件動作。
  • 部分私人訊息。舉例來說，Chat 應用程式無法傳送含有文字和資訊卡的訊息，且該訊息只有一位使用者可以看見，但聊天室中的所有成員都能看到該資訊卡。
  • 使用者驗證。只有 Chat 應用程式可以傳送私人訊息，因此 Chat 應用程式無法以使用者身分進行驗證，也無法私下傳送訊息。

更新或刪除私人訊息

如要更新或刪除 Google Chat 訊息，您必須呼叫 Chat API。您無法變更私人訊息的檢視者或公開該訊息。因此，更新私人訊息時，您必須在 API 呼叫中省略 privateMessageViewer 欄位 (該欄位僅供輸出)。

如要更新私人訊息，請參閱「更新訊息」。如要刪除私人訊息，請參閱「刪除訊息」一節。