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

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

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

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

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

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

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

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

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

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

.

Node.js

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

Apps Script

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

Python

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

Java

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

הגדרה של פקודת קו נטוי

בקטע הזה מוסבר איך להגדיר קו נטוי הפקודה:

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

בחירת שם לפקודת הלוכסן

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

שם ותיאור של פקודה
איור 2: השם והתיאור של פקודה בקו נטוי.

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

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

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

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

    • התיאור צריך להיות קצר וברור כדי שהמשתמשים ידעו למה לצפות כשהוא מפעיל את הפקודה.
    • חשוב ליידע את המשתמשים אם יש דרישות פורמט כלשהן לפקודה. לדוגמה, אם יוצרים פקודת /remindMe שמחייבת ארגומנט text, צריך להגדיר את התיאור כך שיהיה משהו כמו 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, לוחצים על 'תפריט'. > ממשקי API ו- שירותים > ממשקי API מופעלים שירותים > Google Chat API

    כניסה לדף Google Chat API

  2. לוחצים על Configuration.

  3. בקטע SlashCommand, לוחצים על Add a לוכסן הפקודה.

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

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

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

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

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

תשובה לפקודה של קו נטוי

כשמשתמשים יוצרים הודעת Chat שמכילה פקודה של קו נטוי, אפליקציית Chat מקבלת אירוע אינטראקציה אחד (MESSAGE). המטען הייעודי (payload) של האירוע מכיל את הפרמטר 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:
    JsonObject aboutMessage = new JsonObject();
    aboutMessage.addProperty("text", "The Avatar app replies to Google Chat messages.");
    aboutMessage.add("privateMessageViewer", body.getAsJsonObject("user"));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
  }
}

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