איך עונים לפקודות דרך שורת הפקודה ב-Google Chat

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

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

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

איך משתמשים משתמשים בפקודות הלוכסן

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

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

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

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

הגדרת פקודה דרך שורת הפקודה

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

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

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

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

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

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

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

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

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

   כניסה לדף Google Chat API

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

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

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

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

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

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

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

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

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

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

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

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

// 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 messages 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 chatMessage = req.body.chat.messagePayload.message;

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

    // 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;

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

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

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