פיתוח ממשקים ב-Google Chat

בדף הזה מפורטת סקירה כללית על פיתוח ממשקי משתמש (UI) לתוספים של Google Workspace שמרחיבים את Google Chat.

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

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

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

אפליקציות צ'אט יכולות ליצור ולהציג כרטיסים בממשקים הבאים:

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

טריגרים

בקטע הזה מוסבר על הטריגרים שבהם משתמשים התוספים של Google Workspace ב-Chat.

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

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

טריגר תיאור תגובה אופיינית
נוסף למרחב המשותף

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

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

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

  • שליחת הודעה במרחב של צ'אט אישי (DM) באמצעות אפליקציית Chat.
  • @ציון של אפליקציית Chat בכל סוג של מרחב.
  • שליחת הודעה שמכילה קישור שתואם לדפוס כתובת ה-URL של תצוגות מקדימות של קישורים.
  • מקלידים טקסט בתפריט הבחירה המרובה של הווידג'ט של selectionInput.
 התשובה של אפליקציית Chat תהיה מבוססת על תוכן ההודעה. לדוגמה, אפליקציית Chat משיבה לפקודת הפסיק /about עם הודעה שמסבירה את המשימות שאפליקציית Chat יכולה לבצע.
הוסר מהמרחב המשותף

משתמש מסיר את אפליקציית Chat ממרחבים משותפים, או שאדמין ב-Google Workspace מסיר את אפליקציית Chat ממשתמש בארגון.

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

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

משתמש משתמש בפקודה של אפליקציית Chat.

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

בניגוד לתוספים אחרים של Google Workspace, צריך להגדיר פונקציות חזרה (callbacks) לטריגרים האלה באמצעות Google Chat API. להנחיות, קראו את המאמר הגדרת אפליקציית Google Chat.

במדריכים הבאים מוסבר איך להגיב לטריגר:

אובייקטים של אירועים

בקטע הזה מוסבר מהם כל הרכיבים של אובייקטים של אירועים ב-Chat. מידע נוסף זמין במאמר אובייקטים של אירועים.

אובייקט אירוע
commonEventObject object (CommonEventObject)
אובייקט שמכיל מידע שכל אובייקטי האירועים מכילים, ללא קשר לאפליקציית המארח.
chat object (Chat)
אובייקט שמכיל את כל המידע על אינטראקציות ב-Chat.

צ'אט

צ'אט
chat.user object (User)
משתמש Chat שביצע אינטראקציה עם אפליקציית Chat.
chat.space object (Space)
המרחבים המשותפים ב-Chat שבהם משתמשים קיימו אינטראקציה עם אפליקציית Chat.
chat.eventTime

string (Timestamp format)

השעה שבה התרחשה האינטראקציה.

שדה האיחוד payload.

הערך של payload יכול להיות רק אחת מהאפשרויות הבאות:
chat.messagePayload

object (MessagePayload)

עומס העבודה שאפליקציות Chat מקבלות מטריגר Message.
chat.addedToSpacePayload

object (AddedToSpacePayload)

נתוני העומס שמיועדים לשימוש (payload) שאפליקציות Chat מקבלות מטריגר נוסף למרחב המשותף.
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

נתוני העומס שכל אפליקציית Chat מקבלת מטריגר הוסרה מהמרחב המשותף.
chat.buttonClickedPayload

object (ButtonClickedPayload)

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

object (WidgetUpdatedPayload)

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

האובייקט CommonEventObject.parameters['autocomplete_widget_query'] מכיל את ערך המחרוזת שהמשתמש מקלידים בתפריט.

chat.appCommandPayload

object (AppCommandPayload)

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

מטען ייעודי

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

מטען ייעודי (payload) של הודעה
MessagePayload
chat.messagePayload.message object (Message)
הודעה ב-Chat שהפעילה את האירוע.
chat.messagePayload.space object (Space)
המרחבים ב-Chat שבהם משתמש שלח את ההודעה שהפעילה את אפליקציית Chat.
chat.messagePayload.configCompleteRedirectUri string
כתובת ה-URL שאליה אפליקציית Chat צריכה להפנות את המשתמש אחרי שהוא משלים תהליך הרשאה או תהליך הגדרה מחוץ ל-Google Chat. מידע נוסף זמין במאמר חיבור התוסף של Google Workspace לשירות של צד שלישי.

נוסף למטען הייעודי לחלל
AddedToSpacePayload
chat.addedToSpacePayload.space object (Space)
המרחבים המשותפים ב-Chat שהמשתמש הוסיף או התקין בהם את אפליקציית Chat.

כשאדמינים מתקינים אפליקציות ל-Chat, השדה space.adminInstalled מוגדר ל-true.

chat.addedToSpacePayload.interactionAdd boolean
האם משתמש הוסיף את אפליקציית Chat למרחב המשותף באמצעות הודעה. לדוגמה, להשתמש ב-@mention לאפליקציית Chat או להשתמש בפקודה. אם true, מערכת Chat שולחת אובייקט אירוע נוסף עם messagePayload שמכיל מידע על ההודעה.
chat.addedToSpacePayload.configCompleteRedirectUri string
כתובת ה-URL שאליה אפליקציית Chat צריכה להפנות את המשתמש אחרי שהוא משלים תהליך הרשאה או תהליך הגדרה מחוץ ל-Google Chat. מידע נוסף זמין במאמר חיבור התוסף של Google Workspace לשירות של צד שלישי.

הוסר ממטען החלל
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
מרחב Chat שממנו המשתמש הסיר או ה uninstall את אפליקציית Chat.

כשאדמינים מסירים אפליקציות ל-Chat, השדה space.adminInstalled מוגדר ל-false.

עומס העבודה של לחיצה על הלחצן
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
הודעת Chat שמכילה את הלחצן שעליו המשתמש לחץ.
chat.buttonClickedPayload.space object (Space)
המרחבים המשותפים ב-Chat שבהם המשתמש לחץ על לחצן בהודעה באפליקציית Chat.
chat.buttonClickedPayload.isDialogEvent boolean
האפשרות הזו מציינת אם המשתמש לחץ על הכפתור כדי ליצור אינטראקציה עם תיבת דו-שיח.
chat.buttonClickedPayload.dialogEventType enum (DialogEventType)
אם הערך של isDialogEvent הוא true, סוג האינטראקציה בתיבת דו-שיח.

טיפוס enum‏ DialogEventType.

הערך של dialogEventType יכול להיות רק אחד מהערכים הבאים:
TYPE_UNSPECIFIED ערך ברירת המחדל. לא צוין.
REQUEST_DIALOG משתמש מבקש תיבת דו-שיח. לדוגמה, הם משתמשים בפקודה או לוחצים על לחצן בהודעה.
SUBMIT_DIALOG משתמש לוחץ על אלמנט אינטראקטיבי בתוך תיבת דו-שיח. לדוגמה, משתמש ממלא פרטים בתיבת דו-שיח ולוחץ על לחצן כדי לשלוח את הפרטים.

מטען נתונים מעודכן של הווידג'ט
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
המרחבים ב-Chat שבהם התרחשה האינטראקציה.

המטען של פקודת האפליקציה
AppCommandPayload
chat.appCommandPayload.appCommandMetadata object (AppCommandMetadata)
מטא-נתונים על הפקודה שבה המשתמש השתמש ועל האופן שבו הוא הפעיל את הפקודה.
chat.appCommandPayload.space object (Space)
מרחב העבודה ב-Chat שבו משתמש השתמש בפקודה.
chat.appCommandPayload.thread object (Thread)
אם האינטראקציה התרחשה בשרשור, שרשור הצ'אט שבו המשתמש השתמש בפקודה.
chat.appCommandPayload.message object (Message)
בפקודות דרך שורת הפקודה, ההודעה שמכילה את הפקודה דרך שורת הפקודה.
chat.appCommandPayload.configCompleteRedirectUri string
אם נדרשת הרשאה או הגדרה לפקודה, כתובת URL להפניה אוטומטית של המשתמש אליה אחרי שהוא משלים את התהליך מחוץ ל-Google Chat.
chat.appCommandPayload.isDialogEvent boolean
האם הפקודה פותחת תיבת דו-שיח.
chat.appCommandPayload.dialogEventType enum (DialogEventType)
סוג האינטראקציה עם תיבת דו-שיח.

טיפוס enum‏ DialogEventType.

הערך של dialogEventType יכול להיות רק אחד מהערכים הבאים:
TYPE_UNSPECIFIED ערך ברירת המחדל. לא צוין.
REQUEST_DIALOG משתמש מבקש תיבת דו-שיח. לדוגמה, הם משתמשים בפקודה או לוחצים על לחצן בהודעה.
SUBMIT_DIALOG משתמש לוחץ על אלמנט אינטראקטיבי בתוך תיבת דו-שיח. לדוגמה, משתמש ממלא פרטים בתיבת דו-שיח ולוחץ על לחצן כדי לשלוח את הפרטים.
מטא-נתונים של פקודות באפליקציה
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string (int64 format)

מזהה הפקודה.
chat.appCommandPayload.appCommandMetadata.appCommandType enum (AppCommandType)
סוג הפקודה.

טיפוס enum‏ AppCommandType.

הערך של AppCommandType יכול להיות רק אחד מהערכים הבאים:
APP_COMMAND_TYPE_UNSPECIFIED ערך ברירת המחדל. לא צוין.
SLASH_COMMAND כדי להשתמש בפקודה, משתמשים שולחים הודעה שמתחילה בקו נטוי /.
QUICK_COMMAND המשתמש בוחר את הפקודה מתפריט Chat באזור התשובה להודעה.

פעולות בצ'אט

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

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

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

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

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

מענה באמצעות Google Chat API

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

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

למידע על אימות של Chat API והפעלת קריאות אליו, ראו סקירה כללית על Chat API.