איך עונים לפקודות באפליקציית 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].
• אפשר להודיע למשתמשים אם האפליקציה תגיב לכולם במרחב המשותף או רק למשתמש שהפעיל את הפקודה. לדוגמה, לפקודה המהירה 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. לוחצים על Configuration (הגדרה).

3. בקטע פקודות, לוחצים על הוספת פקודה.

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

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

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

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

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

איך עונים לפקודות

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

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

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

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

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

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

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

הקוד הבא מציג דוגמה לאפליקציית Chat שמגיבה לפקודת הפסיק /about. אפליקציית Chat מטפלת באירועי אינטראקציה מסוג 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 שמגיבה לפקודה המהירה Help. אפליקציית 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 שמשתמשות בפקודות
• איך שולחים הודעה
• פתיחת תיבת דו-שיח אינטראקטיבית