שליחת הודעות ב-Google Chat

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

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

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

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

Node.js

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

Apps Script

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

עיצוב ההודעה

באפליקציות צ'אט אפשר לכלול בהודעה כל אחד מהפרטים הבאים:

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

למידע נוסף על עיצוב הודעות, תוכלו לעיין במסמכי העזרה הבאים של Google Chat API:

מענה באמצעות שליחת הודעה

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

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

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

כדי להשיב בהודעה, מחזירים את הפעולה DataActions עם אובייקט CreateMessageAction:

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
  "message": MESSAGE
}}}

מחליפים את MESSAGE במשאב Message מ-Chat API. מידע נוסף על הפעולות מפורט במאמר פעולות ב-Chat.

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

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Workspace Add-on.
 * @param {Object} res The response object from the Chat app. An onboarding message that
 *                     introduces the app and helps people get started with it.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  const chatEvent = req.body.chat;
  // Send an onboarding message when added to a Chat space
  if (chatEvent.addedToSpacePayload) {
    res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      text: 'Hi, Cymbal at your service. I help you manage your calendar' +
            'from Google Chat. Take a look at your schedule today by typing' +
            '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn' +
            'what else I can do, type `/help`.'
    }}}}});
  }
};

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. An onboarding message that
 *                  introduces the app and helps people get started with it.
 */
function onAddedToSpace(event) {
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: 'Hi, Cymbal at your service. I help you manage your calendar' +
          'from Google Chat. Take a look at your schedule today by typing' +
          '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn' +
          'what else I can do, type `/help`.'
  }}}}};
}

דוגמת הקוד מחזירה את הודעת הטקסט הבאה:

דוגמה להודעת קליטה.

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

עדכון הודעה

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

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

{ "hostAppDataAction": { "chatDataAction": { "updateMessageAction": {
  "message": MESSAGE
}}}}

מחליפים את MESSAGE במשאב Message מ-Chat API.

מידע נוסף על הפעולות מפורט במאמר פעולות ב-Chat.

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

איך עונים לאינטראקציות או שולחים הודעות יזום באמצעות Google Chat API

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

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

כדי לשלוח הודעה באמצעות Chat API, צריך להגדיר אימות ולקרוא ל-method ‏create() במשאב Message. במאמר שליחת הודעה באמצעות Google Chat API מוסבר איך עושים את זה.