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

הערה: במדריך הזה מוסבר איך לבנות אפליקציית Chat אינטראקטיבית באמצעות אירועי אינטראקציה של Chat API. אפשר גם לבנות אפליקציה ל-Chat כתוסף ל-Google Workspace. מידע על המסגרת שבה כדאי להשתמש זמין במאמר יצירת אפליקציית Google Chat אינטראקטיבית.

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

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

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

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

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

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

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

• 

  איור 1. משתמשים יכולים לגלות פקודות ולכתוב אותן על ידי הקלדת לוכסן / באזור התשובה ואז שם הפקודה.

• 
  איור 2. משתמשים יכולים לראות את הפקודות המהירות ולהשתמש בהן בתפריט
  שמופיע באזור התשובה של הודעה ב-Chat.

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

הערה: דוגמאות הקוד במדריך הזה נכתבו להפעלה כפונקציית Google Cloud עבור Node.js, ‏ Python ו-Java.

Node.js

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

Apps Script

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

Python

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

Java

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

הגדרת הפקודה

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

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

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

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

איור 3: השם והתיאור של פקודה דרך שורת הפקודות.

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

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

• כדאי להשתמש במילים או בביטויים קצרים, תיאוריים ופרקטיים כדי שהפקודות יהיו ברורות למשתמש. לדוגמה, במקום השם 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, מבצעים את השלבים הבאים:

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

   כניסה לדף Google Chat API

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

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

4. מזינים מזהה פקודה, תיאור, סוג פקודה ושם לפקודה:

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

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

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

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

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

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

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

אפליקציה ל-Chat מגיבה באופן פרטי לפקודת הסלאש /help ומסבירה איך לקבל תמיכה.

כדי להגיב לכל סוג של פקודה, צריך לטפל בסוגים שונים של אירועים ובאובייקטים של מטא-נתונים במטען הייעודי (payload) של האירוע:

סוג הפקודה	סוג אירוע	מטא-נתונים של פקודות
פקודה דרך שורת הפקודות	MESSAGE	‫message.slashCommand או message.annotation.slashCommand
פקודה מהירה	APP_COMMAND	appCommandMetadata

בקטעים הבאים מוסבר איך להשיב לפקודה באמצעות הודעה.

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

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

Node.js

node/avatar-app/index.js

הצגת הקוד ב-GitHub

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

Apps Script

apps-script/avatar-app/avatar-app.gs

הצגת הקוד ב-GitHub

// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/avatar-app/main.py

הצגת הקוד ב-GitHub

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

Java

java/avatar-app/src/main/java/AvatarApp.java

הצגת הקוד ב-GitHub

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

מחליפים את ABOUT_COMMAND_ID במזהה הפקודה שצוין כשמגדירים את הפקודה במסוף Google Cloud.

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

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

Node.js

node/avatar-app/index.js

הצגת הקוד ב-GitHub

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

Apps Script

apps-script/avatar-app/avatar-app.gs

הצגת הקוד ב-GitHub

/**
 * Handles the APP_COMMAND event type. This function is triggered when a user
 * interacts with a quick command within the Google Chat app.  It responds
 * based on the command ID.
 *
 * @param {Object} event The event object from Google Chat, containing details
 *     about the app command interaction.  It includes information like the
 *     command ID and the user who triggered it.
 */
function onAppCommand(event) {
  // Executes the quick command logic based on its ID.
  // Command IDs are set in the Google Chat API configuration.
  switch (event.appCommandMetadata.appCommandId) {
    case HELP_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/avatar-app/main.py

הצגת הקוד ב-GitHub

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

Java

java/avatar-app/src/main/java/AvatarApp.java

הצגת הקוד ב-GitHub

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

מחליפים את HELP_COMMAND_ID במזהה הפקודה שצוין כשמגדירים את הפקודה במסוף Google Cloud.

בדיקת הפקודה

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

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

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

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