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

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

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

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

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

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

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

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

לדוגמה, כדי לקבל מידע על אפליקציה ב-Chat שהמשתמשים גילו במרחב משותף, הם יכולים להשתמש בפקודות כמו /about או /help. כדי שלא תישלח הודעה לכל המשתתפים במרחב המשותף, אפליקציית 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. יוצרים שם לפקודת ה-slash.
  2. מגדירים את הפקודה הלוכסן ב-Google Chat API.

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

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

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

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

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

    • כדאי להשתמש במילים או בביטויים קצרים, תיאוריים ופועליים כדי שהפקודות יהיו ברורות ופשוטה למשתמש. לדוגמה, במקום להזין /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 ו Services (שירותים) > ממשקי API מופעלים Services (שירותים) > 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. לוחצים על שמירה.

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