本頁面說明如何以 Google Chat 應用程式的形式建立及傳送私人訊息。
私人訊息是 Chat 應用程式訊息,只有特定 Chat 使用者能看得見。您可以在聊天室中與多人使用私人訊息,讓他們與 Chat 應用程式進行私密互動。舉例來說,Chat 應用程式可透過私密方式傳送訊息,以執行下列任一操作:
- 回應斜線指令。舉例來說,如果使用者在聊天室中叫用 Chat 應用程式的
/about
斜線指令,您的 Chat 應用程式就能以私人訊息回覆,說明 Chat 應用程式的用途和使用方式。 - 僅通知或傳送只與一位使用者相關的資訊。例如,通知使用者已獲派工作,或提醒他們完成工作。
- 傳送錯誤訊息。舉例來說,如果使用者省略斜線指令的必要引數文字,Chat 應用程式就會傳送私人訊息,藉此說明錯誤內容,並協助使用者設定指令的格式。
當 Chat 應用程式傳送私人訊息時,訊息會顯示標籤,通知使用者該訊息僅供檢視:
必要條件
Node.js
- 已啟用並設定 Google Chat API 的 Google Cloud 專案。相關步驟請參閱「建構 Google Chat 應用程式」。
- 如要私下回應斜線指令,請為 Chat 應用程式設定的斜線指令。如要建構斜線指令,請參閱回應斜線指令。
- 如要使用
messages.create()
方法傳送私人訊息,您必須使用應用程式驗證。
注意事項:本指南中的 Node.js 程式碼範例都已編寫為 Google Cloud 函式執行。
Python
- 已啟用並設定 Google Chat API 的 Google Cloud 專案。相關步驟請參閱「建構 Google Chat 應用程式」。
- 如要私下回應斜線指令,請為 Chat 應用程式設定的斜線指令。如要建構斜線指令,請參閱回應斜線指令。
- 如要使用
messages.create()
方法傳送私人訊息,您必須使用應用程式驗證。
注意事項:本指南中的 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
欄位 (該欄位僅供輸出)。
如要更新私人訊息,請參閱「更新訊息」。如要刪除私人訊息,請參閱「刪除訊息」一節。