איך עונים לפקודות באפליקציית Google Chat

בדף הזה מוסבר איך להגדיר אפליקציה ל-Google Chat ולענות לפקודות.

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

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

סוגים של פקודות לאפליקציות ל-Chat

1. פקודות דרך שורת הפקודות: המשתמשים יכולים לבחור פקודה דרך שורת הפקודות מהתפריט או להקליד לוכסן (/) ואז טקסט מוגדר מראש, כמו /about. בדרך כלל, כדי להשתמש בפקודות דרך שורת הפקודות באפליקציות צ'אט, צריך להזין טקסט של ארגומנט.

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

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

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

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

הגדרת הפקודה

בקטע הזה מוסבר איך לבצע את השלבים הבאים כדי להגדיר פקודה:

1. נותנים שם ומוסיפים תיאור לפקודה.
2. מגדירים את הפקודה במסוף Google Cloud.

נותנים שם לפקודה ומתארים אותה

השם של הפקודה הוא מה שהמשתמשים מקלידים או בוחרים כדי להפעיל את אפליקציית Chat. מתחת לשם מופיע גם תיאור קצר, כדי לעזור למשתמשים להבין איך להשתמש בפקודה:

כשבוחרים שם ותיאור לפקודה, כדאי להביא בחשבון את ההמלצות הבאות:

כדי לתת שם לפקודה:

• כדאי להשתמש במילים או בביטויים קצרים, תיאוריים ופרקטיים כדי שהפקודות יהיו ברורות למשתמש. לדוגמה, במקום השם Create a reminder, משתמשים בשם Remind me.
• כדאי להשתמש בשם ייחודי או נפוץ לפקודה. אם הפקודה מתארת אינטראקציה או תכונה טיפוסיות, אפשר להשתמש בשם נפוץ שהמשתמשים מכירים ומצפים לו, כמו Settings או Feedback. אחרת, כדאי להשתמש בשמות פקודות ייחודיים, כי אם שם הפקודה שלכם זהה לשם של פקודה באפליקציות אחרות של Chat, המשתמש יצטרך לסנן בין פקודות דומות כדי למצוא את הפקודה שלכם ולהשתמש בה.

כדי לתאר פקודה:

• התיאור צריך להיות קצר וברור כדי שהמשתמשים ידעו למה לצפות כשהם משתמשים בפקודה.
• ליידע את המשתמשים אם יש דרישות פורמט לפקודה. לדוגמה, אם אתם יוצרים פקודת לוכסן שדורשת טקסט של ארגומנט, אתם יכולים להגדיר את התיאור כך: Remind me to do [something] at [time].
• צריך להודיע למשתמשים אם אפליקציית Chat עונה לכולם במרחב, או באופן פרטי למשתמש שמפעיל את הפקודה. לדוגמה, אם רוצים לתת תיאור לפקודה המהירה About, אפשר לכתוב Learn about this app (Only visible to you).

הגדרת הפקודה במסוף Google Cloud

כדי ליצור פקודה מהירה או פקודה עם לוכס, מציינים את פרטי הפקודה בהגדרות של אפליקציית Chat עבור Google Chat API.

כדי להגדיר פקודה ב-Google Chat API, מבצעים את השלבים הבאים: כדי להגדיר פקודת לוכסן ב-Google Chat API, מבצעים את השלבים הבאים:

1. במסוף Google Cloud, לוחצים על סמל התפריט menu > APIs & Services ‏> Enabled APIs & Services ‏> Google Chat API.

   כניסה לדף Google Chat API

2. לוחצים על הגדרה.

3. בקטע הגדרות חיבור, עוברים אל טריגרים ומציינים את פרטי נקודת הקצה. צריך להשתמש בטריגר הזה בקטע הבא כדי להגיב לפקודה.

   1. כתובת URL של נקודת קצה (endpoint) בפרוטוקול HTTP: אפשר לציין כאן כתובת URL אחת משותפת של נקודת קצה (endpoint) בפרוטוקול HTTP. לחלופין, כדי להשתמש בנקודות קצה שונות של HTTP עבור טריגרים שונים, מציינים את נקודת הקצה ישירות בשדה App command (פקודת האפליקציה).
   2. ‫Apps Script: מזינים את מזהה הפריסה של Apps Script. כברירת מחדל, הפונקציה onAppCommand תופעל. כדי להשתמש בפונקציית Apps Script אחרת, מציינים את שם הפונקציה המותאמת אישית בשדה App command.

4. בקטע Commands, לוחצים על Add a command.

5. מזינים את הפרטים הבאים לגבי הפקודה:

   1. מזהה הפקודה: מספר מ-1 עד 1,000 שמשמש את אפליקציית Chat לזיהוי הפקודה ולהחזרת תשובה.
   2. תיאור: הטקסט שמתאר איך להשתמש בפקודה ואיך לעצב אותה. התיאורים יכולים לכלול עד 50 תווים.
   3. סוג הפקודה: בוחרים באפשרות פקודה מהירה או פקודת לוכסן.
   4. מציינים שם לפקודה המהירה או לפקודה דרך שורת הפקודות:
      • שם הפקודה המהירה: השם המוצג שהמשתמשים בוחרים מהתפריט כדי להפעיל את הפקודה. יכול לכלול עד 50 תווים, כולל תווים מיוחדים. לדוגמה, Remind me.
      • שם הפקודה דרך שורת הפקודות: הטקסט שהמשתמשים מקלידים כדי להפעיל את הפקודה בהודעה. הנתיב חייב להתחיל בלוכסן, להכיל רק טקסט ולהיות באורך של עד 50 תווים. לדוגמה, /remindMe.

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

7. לוחצים על שמירה.

הפקודה מוגדרת עכשיו לאפליקציית Chat.

איך מגיבים לפקודה

כשמשתמשים מפעילים פקודה, אפליקציית Chat מקבלת אובייקט אירוע. מטען הייעודי (payload) של האירוע מכיל אובייקט appCommandPayload עם פרטים על הפקודה שהופעלה (כולל מזהה הפקודה וסוג הפקודה), כדי שתוכלו להחזיר תגובה מתאימה. אובייקט האירוע נשלח לנקודת הקצה של HTTP או לפונקציית Apps Script שציינתם כשהגדרתם את הטריגר App command.

בדוגמה הבאה מוצג קוד של אפליקציית Chat שעונה לפקודת הלוכסן /about בהודעת טקסט. כדי להגיב לפקודות עם לוכסן, אפליקציית Chat מטפלת באובייקטים של אירועים מטריגר של פקודת אפליקציה. כשהמטען הייעודי (payload) של אובייקט אירוע מכיל מזהה של פקודת לוכסן, אפליקציית Chat מחזירה את הפעולה DataActions עם אובייקט createMessageAction:

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Handle requests from Google Workspace add on
 *
 * @param {Object} req Request sent by Google Chat
 * @param {Object} res Response to be sent back to Google Chat
 */
http('avatarApp', (req, res) => {
  const chatEvent = req.body.chat;
  let message;
  if (chatEvent.appCommandPayload) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
    message: message
  }}}});
});

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 * @return the response message object.
 */
function handleAppCommand(event) {
  switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return {
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

# The ID of the slash command "/about".
# You must use the same ID in the Google Chat API configuration.
ABOUT_COMMAND_ID = 1

@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
  """Handle requests from Google Workspace add on

  Args:
    flask.Request req: the request sent by Google Chat

  Returns:
    Mapping[str, Any]: the response to be sent back to Google Chat
  """
  chat_event = req.get_json(silent=True)["chat"]
  if chat_event and "appCommandPayload" in chat_event:
    message = handle_app_command(chat_event)
  else:
    message = handle_message(chat_event)
  return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
      "message": message
  }}}}

def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Responds to an APP_COMMAND event in Google Chat.

  Args:
    Mapping[str, Any] event: the event object from Google Chat

  Returns:
    Mapping[str, Any]: the response message object.
  """
  if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
    return {
      "text": "The Avatar app replies to Google Chat messages.",
    }
  return {}

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
private static final int ABOUT_COMMAND_ID = 1;

private static final Gson gson = new Gson();

/**
 * Handle requests from Google Workspace add on
 * 
 * @param request the request sent by Google Chat
 * @param response the response to be sent back to Google Chat
 */
@Override
public void service(HttpRequest request, HttpResponse response) throws Exception {
  JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
  JsonObject chatEvent = event.getAsJsonObject("chat");
  Message message;
  if (chatEvent.has("appCommandPayload")) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  JsonObject createMessageAction = new JsonObject();
  createMessageAction.add("message", gson.fromJson(gson.toJson(message), JsonObject.class));
  JsonObject chatDataAction = new JsonObject();
  chatDataAction.add("createMessageAction", createMessageAction);
  JsonObject hostAppDataAction = new JsonObject();
  hostAppDataAction.add("chatDataAction", chatDataAction);
  JsonObject dataActions = new JsonObject();
  dataActions.add("hostAppDataAction", hostAppDataAction);
  response.getWriter().write(gson.toJson(dataActions));
}

/**
 * Handles an APP_COMMAND event in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return the response message object.
 */
private Message handleAppCommand(JsonObject event) throws Exception {
  switch (event.getAsJsonObject("appCommandPayload")
    .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
    case ABOUT_COMMAND_ID:
      return new Message()
        .setText("The Avatar app replies to Google Chat messages.");
    default:
      return null;
  }
}

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {
  // Executes the app command logic based on ID.
  switch (event.chat.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'The Avatar app replies to Google Chat messages.'
      }}}}};
  }
}

כדי להשתמש בדוגמת הקוד הזו, צריך להחליף את ABOUT_COMMAND_ID במזהה הפקודה שציינתם כשהגדרתם את הפקודה ב-Chat API.

בדיקת הפקודה

כדי לבדוק את הפקודה והקוד, אפשר לעיין במאמר בדיקת תכונות אינטראקטיביות באפליקציות ל-Google Chat.

במאמר איך משתמשים באפליקציות ב-Google Chat שבתיעוד העזרה של Google Chat מוסבר איך לבדוק את הפקודה ולהשתמש בה בממשק המשתמש של Chat.

נושאים קשורים

• דוגמאות לאפליקציות ל-Chat שמשתמשות בפקודות
• לשלוח הודעה
• פתיחת תיבות דו-שיח אינטראקטיביות