שליחת הודעות פרטיות למשתמשי Google Chat

בדף הזה מוסבר איך ליצור ולשלוח הודעות פרטיות כאפליקציית Google Chat.

הודעה פרטית היא הודעה מאפליקציית Chat שגלויה רק למשתמש מסוים ב-Chat. אתם יכולים להשתמש בצ'אטים פרטיים במרחבים עם כמה אנשים, כדי שהם יוכלו לתקשר עם אפליקציות צ'אט בפרטיות. לדוגמה, אפליקציית Chat יכולה לשלוח הודעות באופן פרטי כדי לבצע את הפעולות הבאות:

  • להגיב לפקודה לוכסן. לדוגמה, אם משתמש מפעיל את פקודת הלוכסן /about של אפליקציית Chat במרחב המשותף, האפליקציה של Chat יכולה לענות עם הודעה פרטית שמסבירה מה אפליקציית Chat פועלת ואיך להשתמש בה.
  • שולחים התראה או שולחים מידע שרלוונטי למשתמש אחד בלבד. לדוגמה, אפשר להודיע למשתמש שהוקצה לו משימה או להזכיר לו להשלים את המשימה.
  • שליחת הודעת שגיאה. לדוגמה, אם משתמש משמיט את טקסט הארגומנט הנדרש בפקודת לוכסן, אפליקציית Chat יכולה לשלוח הודעה פרטית כדי להסביר את השגיאה ולעזור למשתמש לעצב את הפקודה.

כשאפליקציית Chat שולחת הודעה פרטית, מוצגת הודעה למשתמש עם תווית שמיידעת את המשתמש שההודעה גלויה רק לו:

הודעה פרטית לאפליקציית Cymbal Labs Chat. בהודעה נכתב שאפליקציית Chat נוצרה על ידי Cymbal Labs ומשתפת קישור למסמכי התיעוד וקישור ליצירת קשר עם צוות התמיכה.
איור 1: כשאפליקציית Chat שולחת הודעה פרטית, המשתמש רואה הודעה עם התווית Only visible to you.

דרישות מוקדמות

Node.js

הערה: דוגמאות הקוד של Node.js במדריך הזה נכתבות כפונקציה של Google Cloud Functions.

Python

הערה: דוגמאות הקוד של Python שמפורטות במדריך הזה נכתבות כפונקציה של Google Cloud Functions, באמצעות Python 3.10.

Apps Script

מעכשיו אפשר לשלוח הודעה פרטית

כדי לשלוח הודעה באופן פרטי כאפליקציית 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 (השדה הוא פלט בלבד).

במאמר עדכון הודעה מוסבר איך מעדכנים הודעה פרטית. במאמר מחיקת הודעה מוסבר איך מוחקים הודעות פרטיות.