בדף הזה מוסבר איך ליצור ולשלוח הודעות פרטיות כאפליקציית Google Chat.
הודעה פרטית היא הודעה מאפליקציית Chat שגלויה רק למשתמש מסוים ב-Chat. אתם יכולים להשתמש בצ'אטים פרטיים במרחבים עם כמה אנשים, כדי שהם יוכלו לתקשר עם אפליקציות צ'אט בפרטיות. לדוגמה, אפליקציית Chat יכולה לשלוח הודעות באופן פרטי כדי לבצע את הפעולות הבאות:
- להגיב לפקודה לוכסן. לדוגמה, אם משתמש מפעיל את פקודת הלוכסן
/about
של אפליקציית Chat במרחב המשותף, האפליקציה של Chat יכולה לענות עם הודעה פרטית שמסבירה מה אפליקציית Chat פועלת ואיך להשתמש בה. - שולחים התראה או שולחים מידע שרלוונטי למשתמש אחד בלבד. לדוגמה, אפשר להודיע למשתמש שהוקצה לו משימה או להזכיר לו להשלים את המשימה.
- שליחת הודעת שגיאה. לדוגמה, אם משתמש משמיט את טקסט הארגומנט הנדרש בפקודת לוכסן, אפליקציית Chat יכולה לשלוח הודעה פרטית כדי להסביר את השגיאה ולעזור למשתמש לעצב את הפקודה.
כשאפליקציית Chat שולחת הודעה פרטית, מוצגת הודעה למשתמש עם תווית שמיידעת את המשתמש שההודעה גלויה רק לו:
דרישות מוקדמות
Node.js
- פרויקט ב-Google Cloud עם ממשק Google Chat API פעיל ומוגדר. במאמר איך יוצרים אפליקציה ל-Google Chat מוסבר איך עושים זאת.
- איך מגיבים באופן פרטי לפקודה דרך שורת הפקודות? אלו הפקודה שמוגדרת באפליקציית Chat. במאמר מענה לפקודות דרך שורת הפקודות מוסבר איך יוצרים את הפקודה הזו.
- כדי לשלוח הודעה פרטית בשיטה
messages.create()
, צריך להשתמש באימות אפליקציות.
הערה: דוגמאות הקוד של Node.js במדריך הזה נכתבות כפונקציה של Google Cloud Functions.
Python
- פרויקט ב-Google Cloud עם ממשק Google Chat API פעיל ומוגדר. במאמר איך יוצרים אפליקציה ל-Google Chat מוסבר איך עושים זאת.
- איך מגיבים באופן פרטי לפקודה דרך שורת הפקודות? אלו הפקודה שמוגדרת באפליקציית Chat. במאמר מענה לפקודות דרך שורת הפקודות מוסבר איך יוצרים את הפקודה הזו.
- כדי לשלוח הודעה פרטית בשיטה
messages.create()
, צריך להשתמש באימות אפליקציות.
הערה: דוגמאות הקוד של Python שמפורטות במדריך הזה נכתבות כפונקציה של Google Cloud Functions, באמצעות Python 3.10.
Apps Script
- אפליקציה ל-Chat. כדי ליצור אפליקציה ל-Chat, תוכלו להיעזר בquickstart.
- איך מגיבים באופן פרטי לפקודה דרך שורת הפקודות? אלו הפקודה שמוגדרת באפליקציית Chat. במאמר מענה לפקודות דרך שורת הפקודות מוסבר איך יוצרים את הפקודה הזו.
- כדי לשלוח הודעה פרטית בשיטה
messages.create()
, צריך להשתמש באימות אפליקציות.
מעכשיו אפשר לשלוח הודעה פרטית
כדי לשלוח הודעה באופן פרטי כאפליקציית Chat, צריך לציין את השדה privateMessageViewer
בהודעה כשיוצרים אותה. אפשר ליצור הודעות פרטיות בדיוק כמו שיוצרים כל הודעה: על ידי מענה לאינטראקציה של המשתמש או הפעלה אסינכרונית של השיטה create()
ב-Google Chat API במשאב Message
. במאמר שליחת הודעה מוסבר איך שולחים הודעות טקסט או הודעות בכרטיס.
הדוגמה הבאה מציגה את ה-JSON של הודעת טקסט פרטית עם הכיתוב Hello private world!
:
{
"text": "Hello private world!",
"privateMessageViewer": "USER"
}
בדוגמה הזו, USER
מייצג את המשתמש ב-Chat שיכול לראות את ההודעה, בפורמט של משאב 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.'
});
};
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. לא ניתן לשנות את הצופה של ההודעה הפרטית או להפוך את ההודעה לציבורית. לכן כשמעדכנים הודעות פרטיות, צריך להשמיט את השדה privateMessageViewer
בקריאה ל-API (השדה הוא פלט בלבד).
במאמר עדכון הודעה מוסבר איך מעדכנים הודעה פרטית. במאמר מחיקת הודעה מוסבר איך מוחקים הודעות פרטיות.
נושאים קשורים
- איך שולחים הודעה
- זיהוי והגדרה של משתמשי Google Chat
- מענה לפקודות דרך שורת הפקודות
- איך מעדכנים הודעות
- איך מוחקים הודעות?