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

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

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

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

סוגים של פקודות לאפליקציות ל-Chat

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

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

HTTP

תוסף ל-Google Workspace שמרחיב את Google Chat. כדי ליצור אחד, צריך להשלים את המדריך להתחלה מהירה בנושא HTTP.

Apps Script

תוסף ל-Google Workspace שמרחיב את Google Chat. כדי ליצור אחד, צריך להשלים את המדריך למתחילים ב-Apps Script.

הגדרת הפקודה

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

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

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

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

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

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

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

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

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

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

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

    1. כתובת URL של נקודת קצה (endpoint) ב-HTTP: אפשר לציין כאן כתובת URL אחת משותפת של נקודת קצה ב-HTTP. לחלופין, כדי להשתמש בנקודות קצה שונות של HTTP עבור טריגרים שונים, מציינים את נקודת הקצה ישירות בשדה פקודת האפליקציה.
    2. ‫Apps Script: מזינים את מזהה הפריסה של Apps Script. כברירת מחדל, הפונקציה onAppCommand תופעל. כדי להשתמש בפונקציה אחרת של Apps Script, מציינים את השם של הפונקציה המותאמת אישית בשדה App command.

  4. בקטע Commands, לוחצים על Add a command.

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

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

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

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

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

איך מגיבים לפקודה

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

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

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

Node.js 

// 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 }
                        }]
                    }]
                }
            }]
        }}}}});
    }
};

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;

/**
 * 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.