פיתוח ממשקים ב-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)

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

chat.appCommandPayload

object (AppCommandPayload)

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

מטען ייעודי (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 שבהם התרחשה האינטראקציה.

המטען של פקודת האפליקציה
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 כדי להשתמש בפקודה, משתמשים שולחים הודעה שמתחילה בקו נטוי /.

פעולות בצ'אט

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

כדי להגיב באמצעות פעולה של תוסף, אפליקציית צ'אט צריכה להשיב תוך 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.