מענה לפקודות דרך שורת הפקודות כאפליקציית 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. בקטע Slash commands, לוחצים על Add a slash command.

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

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

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

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

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

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

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

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

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

Node.js

node/avatar-app/index.js
// 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 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
# Checks for the presence of a slash command in the message.
if "slashCommand" in request_json["message"]:
  # Executes the slash command logic based on its ID.
  # Slash command IDs are set in the Google Chat API configuration.
  if request_json["message"]["slashCommand"]["commandId"] == ABOUT_COMMAND_ID:
    return {
      "privateMessageViewer": request_json["user"],
      "text": 'The Avatar app replies to Google Chat messages.'
    }

Java

java/avatar-app/src/main/java/App.java
// Checks for the presence of a slash command in the message.
if (body.getAsJsonObject("message").has("slashCommand")) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  JsonObject slashCommand = body.getAsJsonObject("message").getAsJsonObject("slashCommand");
  switch (slashCommand.get("commandId").getAsString()) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
        .setName(body.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
  }
}

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