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

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

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

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

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

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

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

HTTP Apps Script

הגדרת הפקודה

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

  1. יוצרים שם ותיאור לפקודה.
  2. מגדירים את הפקודה במסוף 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 Chat API:

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

    כניסה לדף Google Chat API

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

  3. בקטע Advanced settings, עוברים אל Triggers ובודקים שהשדה App command מכיל טריגר, כמו נקודת קצה מסוג HTTP או פונקציית Apps Script. צריך להשתמש בטריגר הזה בקטע הבא כדי להגיב לפקודה.

  4. בקטע פקודות, לוחצים על הוספת פקודה.

  5. מזינים את הפרטים הבאים לגבי הפקודה:

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

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

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

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

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

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

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

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

Node.js Apps Script 
// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Google Cloud Function that responds to events sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.avatarApp = function avatarApp(req, res) {
    if (req.method === 'GET' || !req.body.chat) {
        return res.send('Hello! This function is meant to be used ' +
            'in a Google Chat Space.');
    }
    // Stores the Google Chat event as a variable.
    const chatEvent = req.body.chat;

    // Handles events that contain payloads about commands
    if (chatEvent.appCommandPayload) {

      // Stores the Google Chat app command metadata as a variable.
      const appCommandMetadata = chatEvent.appCommandPayload.appCommandMetadata;

      // Executes the slash command logic based on its ID.
      // Slash command IDs are set in the Google Chat API configuration.
      switch (appCommandMetadata.appCommandId) {
          case ABOUT_COMMAND_ID:
              return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                  text: 'The Avatar app replies to Google Chat messages.'
              }}}}});
      }
    // Handles MESSAGE events
    } else if (chatEvent.messagePayload) {

        // Stores the Google Chat event as a variable.
        const chatMessage = chatEvent.messagePayload.message;

        // Replies with the sender's avatar in a card otherwise.
        const displayName = chatMessage.sender.displayName;
        const avatarUrl = chatMessage.sender.avatarUrl;
        res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
            text: 'Here\'s your avatar',
            cardsV2: [{
                cardId: 'avatarCard',
                card: {
                    name: 'Avatar Card',
                    header: {
                        title: `Hello ${displayName}!`,
                    },
                    sections: [{
                        widgets: [{
                            textParagraph: { text: 'Your avatar picture: ' }
                        }, {
                            image: { imageUrl: avatarUrl }
                        }]
                    }]
                }
            }]
        }}}}});
    }
};

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {

    // Stores the Google Chat event as a variable.
    const chatMessage = event.chat.messagePayload.message;

    // Replies with the sender's avatar in a card otherwise.
    const displayName = chatMessage.sender.displayName;
    const avatarUrl = chatMessage.sender.avatarUrl;
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'Here\'s your avatar',
        cardsV2: [{
            cardId: 'avatarCard',
            card: {
                name: 'Avatar Card',
                header: {
                    title: `Hello ${displayName}!`,
                },
                sections: [{
                    widgets: [{
                        textParagraph: { text: 'Your avatar picture: ' }
                    }, {
                        image: { imageUrl: avatarUrl }
                    }]
                }]
            }
        }]
    }}}}};
}

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {

  // Stores the Google Chat app command metadata as a variable.
  const appCommandMetadata = event.chat.appCommandPayload.appCommandMetadata;

  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (appCommandMetadata.appCommandId) {
      case ABOUT_COMMAND_ID:
          return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
              text: 'The Avatar app replies to Google Chat messages.'
          }}}}};
  }
}

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

בדיקת הפקודה

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

במאמר שימוש באפליקציות ב-Google Chat במרכז העזרה של Google Chat מוסבר איך לבדוק את הפקודה ולהשתמש בה בממשק המשתמש של Chat.