דף זה תורגם על ידי Cloud Translation API.

איך עונים לפקודות באפליקציית Google Chat

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

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

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

סוגי הפקודות באפליקציית Chat

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

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

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

איור 1. כדי לגלות את הפקודות של שורת הפקודות ולהשתמש בהן, המשתמשים מקלידים קו נטוי / באזור התשובה ואחריו את שם הפקודה.
איור 2. המשתמשים יכולים לגלות את הפקודות המהירות ולהשתמש בהן דרך התפריט באזור התשובה להודעה ב-Chat.

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

Node.jsApps ScriptPythonJava

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

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

הגדרת הפקודה

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

יוצרים שם ותיאור לפקודה.
מגדירים את הפקודה במסוף Google Cloud.

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

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

השם והתיאור של הפקודה דרך שורת הפקודה — **איור 3**: השם והתיאור של פקודה דרך שורת הפקודה.

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

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

כדאי להשתמש במילים או בביטויים קצרים, תיאוריים וניתנים לביצוע כדי שהפקודות יהיו ברורות למשתמש. לדוגמה, במקום השם Create a reminder, צריך להשתמש בשם Remind me.
כדאי להשתמש בשם ייחודי או נפוץ לפקודה. אם הפקודה מתארת אינטראקציה או תכונה אופייניות, אפשר להשתמש בשם נפוץ שהמשתמשים מזהים ומצפים לו, כמו Settings או Feedback. אחרת, נסו להשתמש בשמות ייחודיים לפקודות, כי אם שם הפקודה זהה לאפליקציות צ'אט אחרות, המשתמש יצטרך לסנן פקודות דומות כדי למצוא את הפקודה שלכם ולהשתמש בה.

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

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

הגדרת הפקודה במסוף Google Cloud

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

כדי להגדיר פקודה ב-Google Chat API:

במסוף Google Cloud, לוחצים על סמל התפריט > APIs & Services > Enabled APIs & Services > Google Chat API.

כניסה לדף Google Chat API
לוחצים על Configuration.
בקטע פקודות, לוחצים על הוספת פקודה.
מזינים את מזהה הפקודה, השם, התיאור וסוג הפקודה:
- מזהה הפקודה: מספר מ-1 עד 1,000 שמשמש את אפליקציית Chat לזיהוי הפקודה ולהחזרת תשובה.
- שם: השם המוצג של הפקודה. השמות יכולים להכיל עד 50 תווים ויכולים לכלול תווים מיוחדים.
- Description: הטקסט שמתאר את הפעולה של הפקודה. התיאורים יכולים להכיל עד 50 תווים ויכולים לכלול תווים מיוחדים.
- סוג הפקודה: בוחרים באפשרות פקודה מהירה או פקודה עם קו נטוי.
- אם מגדירים פקודת קו נטוי, מזינים ערך בשדה Slash command name כדי לציין את הטקסט שהמשתמשים צריכים להקליד כדי להפעיל את הפקודה. השם חייב להתחיל בקו נטוי, להכיל רק טקסט ולהיות באורך של עד 50 תווים. לדוגמה, /remindMe.
אם רוצים שתופיע תיבת דו-שיח בתגובה לפקודה באפליקציית Chat, מסמנים את התיבה פתיחת תיבת דו-שיח.
לוחצים על שמירה.

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

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

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

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

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

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

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

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

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

Node.js Apps Script Python Java

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/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/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/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 Apps Script Python Java

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/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/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/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 שמשתמשות בפקודות
איך שולחים הודעה
פתיחת תיבת דו-שיח אינטראקטיבית

איך עונים לפקודות באפליקציית Google Chat

סוגי הפקודות באפליקציית Chat

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

הגדרת הפקודה

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

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

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

הגדרת הפקודה במסוף Google Cloud

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

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

מענה לפקודה מהירה

בדיקת הפקודה

נושאים קשורים