איך עונים לפקודות באפליקציית 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].
  • אפשר להודיע למשתמשים אם האפליקציה תגיב לכולם במרחב המשותף או רק למשתמש שהפעיל את הפקודה. לדוגמה, לפקודה המהירה 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. בקטע Connection settings (הגדרות החיבור), עוברים אל Triggers (טריגרים) ומציינים את פרטי נקודת הקצה. צריך להשתמש בטריגר הזה בקטע הבא כדי להגיב לפקודה.

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

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

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

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

  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 

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