מענה לפקודות דרך שורת הפקודות כאפליקציית Google Chat

בדף הזה נסביר איך להגדיר פקודות קו נטוי (slash) באפליקציית Google Chat ואיך להגיב להן.

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

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

חלון הפקודה דרך שורת הפקודות
איור 1: החלון שמופיע כשמשתמשים מקלידים קו נטוי ב-Google Chat.

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

פקודות דרך שורת הפקודה עם תגובות פרטיות

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

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

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

Node.js

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

Apps Script

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

Python

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

Java

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

הגדרת פקודה דרך שורת הפקודה

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

  1. יוצרים שם לפקודת ה-slash.
  2. מגדירים את פקודת הפסיק הנטוי ב-Google Chat API.

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

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

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

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

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

    • כדאי להשתמש במילים או בביטויים קצרים, תיאוריים ופועליים כדי שהפקודות יהיו ברורות ופשוטה למשתמש. לדוגמה, במקום להזין /createAReminder, צריך להשתמש ב-/remindMe.
    • אם הפקודה מכילה יותר ממילה אחת, כדאי להשתמש באותיות קטנות במילה הראשונה ובאותיות רישיות באות הראשונה של המילים הנוספות כדי לעזור למשתמשים לקרוא את הפקודה. לדוגמה, במקום /updatecontact, צריך להשתמש ב-/updateContact.
    • כדאי להחליט אם להשתמש בשם ייחודי או בשם נפוץ לפקודה. אם הפקודה מתארת אינטראקציה או תכונה אופייניות, אפשר להשתמש בשם נפוץ שהמשתמשים מזהים ומצפים לו, כמו /settingsאו /feedback. לחלופין, נסו להשתמש בשמות ייחודיים לפקודות. אם שם הפקודה זהה לאפליקציות צ'אט אחרות, המשתמש יצטרך לסנן פקודות דומות כדי למצוא את הפקודה שלכם ולהשתמש בה.

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

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

הגדרת פקודת הפסיק ב-Google Chat API

כדי ליצור פקודת קו נטוי, צריך לציין מידע על הפקודה בהגדרות של אפליקציית 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. שם: השם המוצג של הפקודה, והטקסט שהמשתמשים מקלידים כדי להפעיל את האפליקציה. השם חייב להתחיל בקו נטוי, להכיל טקסט בלבד ולהיות באורך של עד 50 תווים.
    2. Description: הטקסט שמתאר איך להשתמש בפקודה ואיך לעצב אותה. התיאורים יכולים להכיל עד 50 תווים.
    3. מזהה הפקודה: מספר מ-1 עד 1,000 שמשמש את אפליקציית Chat לזיהוי שורת הפקודה ולחזרת תשובה.

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

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

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

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

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

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

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

Node.js

node/avatar-app/index.js
/**
 * 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
// 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
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
/**
 * 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 עם מזהה הפקודה שציינתם כשהגדרתם את הפקודה דרך שורת הפקודה ב-Chat API. כדי לבדוק את הקוד הזה, אפשר לעיין במאמר בדיקת תכונות אינטראקטיביות לאפליקציות של Google Chat.