פיתוח ממשקים ב-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 בדרך כלל מגיבים:

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

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

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

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

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

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

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

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

בניגוד לתוספים אחרים של 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)

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

object (RemovedFromSpacePayload)

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

object (ButtonClickedPayload)

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

object (WidgetUpdatedPayload)

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

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

מטען ייעודי (payload)

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

מטען ייעודי (payload) של הודעה
MessagePayload
chat.messagePayload.message object (Message)
הודעה ב-Chat שהפעילה את האירוע.
chat.messagePayload.space object (Space)
המרחבים ב-Chat שבהם משתמש שלח את ההודעה שהפעילה את אפליקציית Chat.

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

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

chat.addedToSpacePayload.interactionAdd boolean
האם משתמש הוסיף את אפליקציית Chat למרחב המשותף באמצעות הודעה. לדוגמה, להשתמש בסימן @ כדי להזכיר את אפליקציית Chat או להשתמש בפקודה עם קו נטוי. אם true, מערכת Chat שולחת אובייקט אירוע נוסף עם messagePayload שמכיל מידע על ההודעה.

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

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

עומס העבודה של הלחצן שנלחץ
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
הודעת הצ'אט שמכילה את הלחצן שעליו המשתמש לחץ.
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 שבו התרחשה האינטראקציה.

פעולות בצ'אט

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

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

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