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

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

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

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

Node.js

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

Apps Script

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

עיצוב ההודעה

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

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

מידע על עיצוב הודעות זמין במאמרי העזרה הבאים של 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 מגיבה לטריגר Added to space (נוסף למרחב) על ידי החזרת הפעולה 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.