הגדרת Google Chat API

לכל אפליקציה ל-Google Chat שאתם יוצרים צריך להיות פרויקט משלה ב-Google Cloud, שבו Chat API מופעל ומוגדר.

כדי לבצע קריאות ל-API לקריאה בלבד עם אימות משתמש, כמו קבלת מרחבים משותפים והצגת רשימת הודעות, צריך רק להפעיל את ה-API וליצור לקוח OAuth.

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

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

• חשבון Business או Enterprise ב-Google Workspace עם גישה ל-Google Chat.
• יוצרים פרויקט ב-Google Cloud.
• מגדירים את מסך ההסכמה של OAuth.
• מפעילים את Google Chat API.

איך בוחרים שם לתצוגה, דמות ותיאור לאפליקציה ל-Chat

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

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

שדה	תיאור	פורמט
שם האפליקציה	השם המוצג של האפליקציה ל-Chat.	עד 25 תווים אלפאנומריים
כתובת ה-URL של הדמות	התמונה שמוצגת בתור הדמות של האפליקציה ל-Chat.	כתובת URL מסוג HTTPS שמפנה לתמונה גרפית ריבועית (PNG או JPEG). הגודל המומלץ הוא 256 על 256 פיקסלים או יותר.
תיאור	תיאור קצר של מטרת האפליקציה ל-Chat.	עד 40 תווים אלפאנומריים

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

לדוגמה, אם קוראים ל-method‏ spaces.create(), השם של האפליקציה ל-Chat יופיע בתיאור של מי שיצר את המרחב, כמו שמוצג בתמונה הבאה:

איור 1. הודעת השיוך שמוצגת ב-Chat כשמשתמשים ב-method‏ spaces.create() כדי ליצור מרחב בשם המשתמש.

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

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

הגדרת אפליקציית הצ'אט במסוף Google Cloud

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

1. במסוף Google Cloud, נכנסים לדף Chat API ולוחצים על הדף Configuration:

   לדף ההגדרות של Chat API

2. בקטע Application info, ממלאים את השדות App name,‏ Avatar URL ו-Description.

3. אופציונלי: בתפריט תחביר תגי העיצוב, בוחרים את תחביר תגי העיצוב שיוגדר כברירת מחדל (Markdown או Chat) להודעות של האפליקציה ל-Chat. במאמר עיצוב הודעות מוסבר בהרחבה על עיצוב טקסט ואיך Chat קובע את תחביר תגי העיצוב לבקשות API.

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

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

   כדי ליצור אפליקציית צ'אט אינטראקטיבית, מפעילים את האפשרות Enable interactive features ומבצעים את הפעולות הבאות:

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

   2. בקטע Connection settings, בוחרים את הארכיטקטורה שבה רוצים להשתמש כדי לקבל אובייקטים של אירועים מ-Chat:

      • כדי להשתמש בשירות HTTP, בוחרים באפשרות HTTP endpoint URL ומזינים כתובת URL.
      • כדי להשתמש בפרויקט של Google Apps Script, בוחרים באפשרות Apps Script ומזינים את מזהה הפריסה של הפרויקט.
      • כדי להשתמש בנציג Dialogflow, בוחרים באפשרות Dialogflow, בוחרים באפשרות Dialogflow CX או Dialogflow ES ומזינים את שם המשאב של הנציג.
      • כדי להשתמש ב-Pub/Sub, בוחרים באפשרות Cloud Pub/Sub ומזינים את שם הנושא.
      אזהרה: אם מזהה הפריסה של Apps Script כבר מאוכלס, פרויקט הענן מחובר לתוסף קיים של Google Workspace. אם מעדכנים את מזהה הפריסה ב-Chat API, מזהה הפריסה מתעדכן בתוסף ויכול להשפיע על דף האפליקציה ב-Google Workspace Marketplace. כדי לבדוק את הגדרות התוסף, אפשר לעיין במאמר הגדרת האפליקציה ב-Google Workspace Marketplace SDK.

   3. אופציונלי: כדי לנתב אובייקטים של אירועים לנקודות קצה או לפונקציות ספציפיות, עוברים אל Connection settings (הגדרות החיבור) > Triggers (טריגרים) ומציינים או מעדכנים את נקודות הקצה או הפונקציות של הקריאה החוזרת (callback) בשביל הטריגרים הבאים של Chat:

      הערה: ב-Apps Script, אם לא מעדכנים את הטריגרים, צריך להטמיע את פונקציות הקריאה החוזרת שמאוכלסות בקטע הזה כברירת מחדל (כמו onMessage,‏ onAddedToSpace,‏ onRemovedFromSpace,‏ onAppCommand ו-onAppHome).
      • דף הבית של האפליקציה (אם האפשרות תמיכה בדף הבית של האפליקציה מופעלת): המשתמש פותח את הכרטיסייה דף הבית בצ'אט אישי עם האפליקציה ל-Chat.
      • הוספה למרחב משותף: משתמש מוסיף את האפליקציה ל-Chat לשיחה קבוצתית או למרחב משותף, או מתקין את האפליקציה ל-Chat לצ'אטים אישיים.
      • הודעה: המשתמש שולח הודעה לאפליקציה ל-Chat. לדוגמה, המשתמש שולח הודעה ישירה לאפליקציה ל-Chat או מתייג אותה באמצעות @במרחב עם כמה אנשים.
      • הוסרה מהמרחב המשותף: משתמש הסיר את האפליקציה ל-Chat מהמרחב המשותף.
      • פקודה לאפליקציה: המשתמש מפעיל פקודה מהירה, פקודה דרך שורת הפקודות או פעולה בהודעה מאפליקציית Chat.

   4. אופציונלי: מוסיפים עוד תכונות אינטראקטיביות, כמו הצעות לפרומפט, פקודות (פקודות מהירות, פקודות דרך שורת הפקודות ופעולות בהודעות) או תצוגות מקדימות של קישורים.

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

5. אופציונלי: בקטע Logs, מסמנים את התיבה Log errors to Logging כדי להשתמש ב-Google Cloud Logging. מידע נוסף מופיע במאמר שאילתות ביומני השגיאות של אפליקציות ל-Chat.

6. לוחצים על שמירה.

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

שיקולים לגבי תוספים קיימים ל-Google Workspace

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

• גם משתמשים פרטיים וגם Google Workspace Administrators צריכים להיות מסוגלים להתקין את התוסף מ-Marketplace. אתם קובעים את הגדרות ההתקנה האלה ב-Google Workspace Marketplace SDK.
• אפליקציות צ'אט לא משתמשות בשם ובלוגו שאתם מגדירים לאפליקציות אחרות של Google Workspace באובייקט addons.common של המניפסט.
• בתוספים שפורסמו ב-Google Workspace Marketplace, אי אפשר לשמור טיוטה של שינויים בהגדרות האישיות של Google Chat API. אחרי שמעדכנים ושומרים את הגדרות התצורה של Chat API, אפליקציית הצ'אט המעודכנת זמינה באופן מיידי לכל המשתמשים הקיימים. כדי לעדכן את דף האפליקציה ב-Marketplace, אתם יכולים ליצור טיוטה לפני שאתם שולחים את השינויים.
• אם פיתחתם את התוסף באמצעות Apps Script:
  • אתם צריכים להשתמש באותו מזהה פריסה של Apps Script שבו אתם משתמשים בשאר ההגדרות של התוסף.
  • אי אפשר להשתמש בעורך של Apps Script כדי להתקין פריסות לבדיקה ב-Chat. במקום זאת, צריך להתקין אותן ישירות מממשק המשתמש של Chat.
• אם פיתחתם את התוסף באמצעות שירות HTTP, אל תכללו פרטים של הגדרת האפליקציה ל-Chat במניפסט ובפריסות שאתם יוצרים באמצעות Google Workspace add-ons API. פריסות ה-HTTP שאתם מציינים ב-Google Workspace Marketplace SDK משמשות רק לאפליקציות אחרות של Google Workspace.

איך נותנים לאנשים אחרים הרשאה להגדיר את Chat API

אתם יכולים לתת למשתמשים ספציפיים גישה לדף ההגדרות של אפליקציית הצ'אט, על ידי הקצאת התפקיד בניהול הזהויות והרשאות הגישה (IAM) של Google Cloud בעלים של אפליקציות צ'אט או צפייה באפליקציות צ'אט. משתמשים עם התפקידים האלה לא יכולים לעבור לדף ההגדרות של אפליקציות ל-Chat באמצעות מרכז הבקרה APIs & Services, אבל הם יכולים לגשת לדף ההגדרות דרך מסוף Google Cloud בפרויקט המארח של האפליקציה ל-Chat ב-Cloud, באופן הבא:

https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

כאשר PROJECT_ID הוא מזהה הפרויקט ב-Google Cloud שמארח את אפליקציית הצ'אט.

משתמשים עם תפקידים בפרויקט יכולים גם לגשת לדף הגדרות האפליקציה.

משתמשים עם תפקידים בהתאמה אישית שכוללים את ההרשאות resourcemanager.projects.(get|update) לא יכולים לגשת להגדרות של אפליקציית Chat. לתפקידים בהתאמה אישית, צריך להשתמש בהרשאות chat.bots.(get|update).

נושאים קשורים

• בחירת ארכיטקטורה לאפליקציה ל-Chat
• קבלת אינטראקציות של משתמשים ושליחת תגובות אליהן
• בדיקת התכונות האינטראקטיביות של אפליקציות ל-Google Chat

אפליקציות ל-Chat שהן לא תוספים: הגדרת Google Chat API

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

1. במסוף Google Cloud, נכנסים לדף Configuration של Chat API:

   לדף ההגדרות של Chat API

2. בקטע תכונות אינטראקטיביות, מפעילים את האפשרות הפעלת תכונות אינטראקטיביות.

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

4. בקטע פונקציונליות, בוחרים באפשרות תמיכה בדף הבית של האפליקציה או באפשרות הצטרפות למרחבים משותפים ולשיחות קבוצתיות, לפי הצורך.

5. בקטע Connection settings, מציינים נקודת קצה אחת לאפליקציה ל-Chat (כתובת URL של נקודת קצה ב-HTTP, מזהה פריסה של Apps Script, שם נושא ב-Cloud Pub/Sub או Dialogflow).

6. מגדירים את האפשרויות Commands,‏ Link previews,‏ Visibility ו-Logs, ולוחצים על Save.

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