במדריך הזה מוסבר איך לקרוא ל-API של Google Chat
messages.create()
לביצוע אחת מהפעולות הבאות:
- שליחת הודעות שמכילות טקסט, כרטיסים וווידג'טים אינטראקטיביים.
- שליחת הודעות פרטיות למשתמש מסוים ב-Chat.
- להתחיל שרשור הודעות או לענות לו.
- אפשר לתת שם להודעה כדי שיהיה אפשר לציין אותה ב-Chat API אחר בקשות.
הגודל המקסימלי של הודעה (כולל טקסט או כרטיסים) הוא 32,000 בייטים. כדי לשלוח הודעה גדולה יותר מהגודל הזה, צריך להשתמש באפליקציית Chat צריך לשלוח מספר הודעות.
נוסף על קריאה ל-method messages.create()
, אפליקציות Chat
יכולים ליצור ולשלוח הודעות כדי להשיב לאינטראקציות של משתמשים, למשל פרסום של
הודעת פתיחה אחרי שמשתמש הוסיף את אפליקציית Chat
המרחב המשותף. אפליקציות צ'אט יכולות להשתמש בפיצ'רים אחרים של תגובות לאינטראקציות
תכונות של העברת הודעות, כולל תיבות דו-שיח אינטראקטיביות ותצוגה מקדימה של קישורים
ממשקים. כדי לענות למשתמש, אפליקציית Chat מחזירה
את ההודעה באופן סינכרוני, בלי לקרוא ל-API של Chat. למידה
על שליחת הודעות כדי להגיב לאינטראקציות,
לקבל אינטראקציות עם אפליקציית Google Chat ולהגיב עליהן.
איך Chat מציג ומשייך הודעות שנוצרו באמצעות Chat API
אפשר לבצע קריאה ל-method messages.create()
באמצעות
אימות אפליקציות
ואימות משתמשים.
אפליקציית Chat משייכת את שולח ההודעה באופן שונה
בהתאם לסוג האימות שבו אתם משתמשים.
כשאתם מבצעים אימות כאפליקציית Chat, ההודעה תישלח מאפליקציית Chat.
App
.כשאתם מבצעים אימות כמשתמשים, אפליקציית Chat שולחת את הודעה בשם המשתמש. Chat גם משייך את אפליקציית Chat שתישלח להודעה באמצעות הצגת השם שלה.
סוג האימות גם קובע אילו תכונות וממשקים של העברת הודעות שאפשר לכלול בהודעה. בעזרת אימות אפליקציות, אפליקציות צ'אט יכולות לשלוח הודעות שמכילות טקסט עשיר, ממשקים מבוססי כרטיסים ווידג'טים אינטראקטיביים. משתמשי Chat יכולים לשלוח רק הודעות טקסט, לכן כלול טקסט בלבד בעת יצירת הודעות באמצעות אימות משתמש. למידע נוסף על התכונה 'העברת הודעות' שזמינות ל-Chat API, סקירה כללית על ההודעות ב-Google Chat
במדריך הזה מוסבר איך להשתמש בכל אחד מסוגי האימות כדי לשלוח הודעה באמצעות Chat API.
דרישות מוקדמות
Node.js
- עסק או ארגון חשבון Google Workspace עם גישה אל Google Chat.
- מגדירים את הסביבה:
- יוצרים פרויקט ב-Google Cloud.
- מגדירים את מסך ההסכמה של OAuth.
- מפעילים ומגדירים את Google Chat API עם שם, הסמל והתיאור של אפליקציית Chat.
- להתקין את Node.js ספריית הלקוח של Cloud.
- יוצרים פרטי כניסה לגישה בהתאם לאופן שבו רוצים לבצע אימות ב-Google Chat API
בקשה:
- כדי לבצע אימות כמשתמשי Chat:
יצירת מזהה לקוח ב-OAuth
פרטי כניסה ולשמור את פרטי הכניסה כקובץ JSON בשם
client_secrets.json
לספרייה המקומית שלך. - כדי לבצע אימות כאפליקציית Chat:
יצירת חשבון שירות
פרטי כניסה ולשמור את פרטי הכניסה כקובץ JSON בשם
credentials.json
.
- כדי לבצע אימות כמשתמשי Chat:
יצירת מזהה לקוח ב-OAuth
פרטי כניסה ולשמור את פרטי הכניסה כקובץ JSON בשם
- בוחרים את היקף ההרשאה בהתאם לאופן שבו רוצים לבצע אימות כמשתמשים או אפליקציית Chat.
- מרחב ב-Google Chat שבו המשתמש המאומת או אפליקציית Chat לשיחות רשומה כמנוי. כדי לבצע אימות בתור אפליקציית Chat, מוסיפים את להשתמש באפליקציית Chat במרחב המשותף.
Python
- עסק או ארגון חשבון Google Workspace עם גישה אל Google Chat.
- מגדירים את הסביבה:
- יוצרים פרויקט ב-Google Cloud.
- מגדירים את מסך ההסכמה של OAuth.
- מפעילים ומגדירים את Google Chat API עם שם, הסמל והתיאור של אפליקציית Chat.
- להתקין את Python ספריית הלקוח של Cloud.
- יוצרים פרטי כניסה לגישה בהתאם לאופן שבו רוצים לבצע אימות ב-Google Chat API
בקשה:
- כדי לבצע אימות כמשתמשי Chat:
יצירת מזהה לקוח ב-OAuth
פרטי כניסה ולשמור את פרטי הכניסה כקובץ JSON בשם
client_secrets.json
לספרייה המקומית שלך. - כדי לבצע אימות כאפליקציית Chat:
יצירת חשבון שירות
פרטי כניסה ולשמור את פרטי הכניסה כקובץ JSON בשם
credentials.json
.
- כדי לבצע אימות כמשתמשי Chat:
יצירת מזהה לקוח ב-OAuth
פרטי כניסה ולשמור את פרטי הכניסה כקובץ JSON בשם
- בוחרים את היקף ההרשאה בהתאם לאופן שבו רוצים לבצע אימות כמשתמשים או אפליקציית Chat.
- מרחב ב-Google Chat שבו המשתמש המאומת או אפליקציית Chat לשיחות רשומה כמנוי. כדי לבצע אימות בתור אפליקציית Chat, מוסיפים את להשתמש באפליקציית Chat במרחב המשותף.
Java
- עסק או ארגון חשבון Google Workspace עם גישה אל Google Chat.
- מגדירים את הסביבה:
- יוצרים פרויקט ב-Google Cloud.
- מגדירים את מסך ההסכמה של OAuth.
- מפעילים ומגדירים את Google Chat API עם שם, הסמל והתיאור של אפליקציית Chat.
- להתקין את Java ספריית הלקוח של Cloud.
- יוצרים פרטי כניסה לגישה בהתאם לאופן שבו רוצים לבצע אימות ב-Google Chat API
בקשה:
- כדי לבצע אימות כמשתמשי Chat:
יצירת מזהה לקוח ב-OAuth
פרטי כניסה ולשמור את פרטי הכניסה כקובץ JSON בשם
client_secrets.json
לספרייה המקומית שלך. - כדי לבצע אימות כאפליקציית Chat:
יצירת חשבון שירות
פרטי כניסה ולשמור את פרטי הכניסה כקובץ JSON בשם
credentials.json
.
- כדי לבצע אימות כמשתמשי Chat:
יצירת מזהה לקוח ב-OAuth
פרטי כניסה ולשמור את פרטי הכניסה כקובץ JSON בשם
- בוחרים את היקף ההרשאה בהתאם לאופן שבו רוצים לבצע אימות כמשתמשים או אפליקציית Chat.
- מרחב ב-Google Chat שבו המשתמש המאומת או אפליקציית Chat לשיחות רשומה כמנוי. כדי לבצע אימות בתור אפליקציית Chat, מוסיפים את להשתמש באפליקציית Chat במרחב המשותף.
Apps Script
- עסק או ארגון חשבון Google Workspace עם גישה אל Google Chat.
- מגדירים את הסביבה:
- יוצרים פרויקט ב-Google Cloud.
- מגדירים את מסך ההסכמה של OAuth.
- מפעילים ומגדירים את Google Chat API עם שם, הסמל והתיאור של אפליקציית Chat.
- יוצרים פרויקט נפרד ב-Apps Script. ומפעילים את שירות Chat המתקדם.
- במדריך זה חובה להשתמש בשני סוגי המשתמשים או אימות אפליקציות. כדי לבצע אימות כאפליקציית Chat, צריך ליצור פרטי הכניסה של חשבון השירות. להוראות, היכנסו למאמר אימות ואישור בתור אפליקציית Google Chat.
- בוחרים את היקף ההרשאה בהתאם לאופן שבו רוצים לבצע אימות כמשתמשים או אפליקציית Chat.
- מרחב ב-Google Chat שבו המשתמש המאומת או אפליקציית Chat לשיחות רשומה כמנוי. כדי לבצע אימות בתור אפליקציית Chat, מוסיפים את להשתמש באפליקציית Chat במרחב המשותף.
שליחת הודעה בתור אפליקציית Chat
בקטע הזה מוסבר איך לשלוח הודעות שמכילות טקסט, כרטיסים ווידג'טים של אביזרים אינטראקטיביים באמצעות אימות אפליקציות.
כדי להפעיל את messages.create()
באמצעות אימות אפליקציות, צריך לציין
השדות הבאים בבקשה:
chat.bot
היקף ההרשאה.- המשאב
Space
שבו שרוצים לפרסם את ההודעה. אפליקציית Chat צריכה להיות משתמש במרחב המשותף. Message
של המשאבים שצריך ליצור. כדי להגדיר את תוכן ההודעה, אפשר לכלול טקסט עשיר (text
), ממשק כרטיס אחד או יותר (cardsV2
), או לשניהם.
אפשר לכלול גם את הפרטים הבאים:
- השדה
accessoryWidgets
שיש לכלול לחצנים אינטראקטיביים בחלק התחתון של ההודעה. - השדה
privateMessageViewer
כדי לשלוח את ההודעה באופן פרטי למשתמש מסוים. - השדה
messageId
, שמאפשר נותנים שם להודעה כדי להשתמש בה בבקשות API אחרות. - השדות
thread.threadKey
ו-messageReplyOption
כדי להתחיל שרשורים או להשיב עליהם. אם לא מוסיפים שימוש בשרשור, המערכת תתעלם מהשדה הזה.
הקוד הבא מציג דוגמה לאופן שבו אפליקציית Chat יש אפשרות לשלוח הודעה שמפורסמת כאפליקציית Chat שמכילה טקסט, כרטיס ולחצן שניתן ללחוץ עליו בתחתית ההודעה:
Node.js
Python
Java
Apps Script
כדי להריץ את הדוגמה הזו, צריך להחליף את SPACE_NAME
במזהה של
של המרחב
השדה name
.
אפשר לקבל את התעודה המזהה בטלפון
שיטת spaces.list()
או מכתובת ה-URL של המרחב המשותף.
הוספת ווידג'טים אינטראקטיביים בתחתית הודעה
בדוגמת הקוד הראשונה במדריך הזה, בהודעה שמופיעה באפליקציית Chat מוצג לחצן שאפשר ללחוץ עליו בחלק התחתון של ההודעה, נקרא ווידג'ט האביזר. ווידג'טים של אביזרים מופיעים אחרי טקסט או כרטיסים בהודעה. אפשר להשתמש בווידג'טים האלה כדי להציג למשתמשים לקיים אינטראקציה עם המסר שלכם בדרכים רבות, כולל:
- מה מידת הדיוק או שביעות הרצון של הודעה?
- מדווחים על בעיה בהודעה או באפליקציית Chat.
- פותחים קישור לתוכן קשור, כמו תיעוד.
- סגירה של הודעות דומות או סימון שהן לטיפול בהמשך באפליקציית Chat לתקופת זמן ספציפית.
כדי להוסיף ווידג'טים של אביזרים, צריך לכלול את
accessoryWidgets[]
בשדה בגוף הבקשה ולציין ווידג'ט אחד או יותר שרוצים
לכלול.
בתמונה הבאה מוצגת אפליקציית Chat הודעת טקסט עם ווידג'טים של אביזרים כדי שהמשתמשים יוכלו לדרג את החוויה שלהם באמצעות אפליקציית Chat.
![ווידג'ט האביזר.](https://google-developers.gonglchuangl.net/static/workspace/chat/images/message-accessory-widgets-reference.png?authuser=1&hl=he)
למטה מוצג גוף הבקשה שיוצר הודעת טקסט עם
שני לחצני אביזרים. כשמשתמש לוחץ על לחצן, הפרמטר התואם
(כמו doUpvote
) מעבדת את האינטראקציה:
{
text: "Rate your experience with this Chat app.",
accessoryWidgets: [{ buttonList: { buttons: [{
icon: { material_icon: {
name: "thumb_up"
}},
color: { red: 0, blue: 255, green: 0 },
onClick: { action: {
function: "doUpvote"
}}
}, {
icon: { material_icon: {
name: "thumb_down"
}},
color: { red: 0, blue: 255, green: 0 },
onClick: { action: {
function: "doDownvote"
}}
}]}}]
}
שליחת הודעה באופן פרטי
אפליקציות צ'אט יכולות לשלוח הודעות בפרטיות, כדי רק משתמש מסוים במרחב המשותף יכול לראות את ההודעה. כאשר אפליקציית Chat תשלח הודעה פרטית מציגה תווית שמיידעת את המשתמש שההודעה גלויה רק לו.
כדי לשלוח הודעה פרטית באמצעות Chat API, צריך לציין את
privateMessageViewer
בגוף הבקשה. כדי לציין את המשתמש, צריך להגדיר את הערך כ-
משאב User
מייצג את המשתמש ב-Chat. אפשר גם להשתמש
השדה name
של
משאב User
, כמו בדוגמה הבאה:
{
text: "Hello private world!",
privateMessageViewer: {
name: "users/USER_ID"
}
}
כדי להשתמש בדוגמה הזו, צריך להחליף את USER_ID
עם מזהה ייחודי של המשתמש, כמו 12345678987654321
או
hao@cymbalgroup.com
. למידע נוסף על ציון משתמשים, ראה
זיהוי וציון משתמשים ב-Google Chat.
כדי לשלוח הודעה באופן פרטי, חובה להשמיט את הפרטים הבאים בבקשה:
שליחת הודעת טקסט בשם משתמש
בקטע הזה מוסבר איך לשלוח הודעות בשם משתמש באמצעות אימות משתמש. באימות משתמש, תוכן ההודעה יכול להכיל רק טקסט וחייבים להשמיט תכונות של העברת הודעות שזמינות רק ללקוחות. אפליקציות צ'אט, כולל ממשקי כרטיסים וווידג'טים אינטראקטיביים.
כדי להפעיל את messages.create()
באמצעות אימות משתמש, צריך לציין את
השדות הבאים בבקשה:
- היקף ההרשאה
שתומך באימות משתמשים בשיטה הזו. הדוגמה הבאה משתמשת
ההיקף
chat.messages.create
. - המשאב
Space
שבו שרוצים לפרסם את ההודעה. המשתמש המאומת חייב להיות חבר המרחב המשותף. Message
של המשאבים שצריך ליצור. כדי להגדיר את תוכן ההודעה, עליך לכלול אתtext
השדה הזה.
אפשר לכלול גם את הפרטים הבאים:
- השדה
messageId
, שמאפשר נותנים שם להודעה כדי להשתמש בה בבקשות API אחרות. - השדות
thread.threadKey
ו-messageReplyOption
כדי להתחיל שרשורים או להשיב עליהם. אם לא מוסיפים שימוש בשרשור, המערכת תתעלם מהשדה הזה.
הקוד הבא מציג דוגמה לאופן שבו אפליקציית Chat יכול לשלוח הודעת טקסט במרחב נתון בשם משתמש מאומת:
Node.js
Python
Java
Apps Script
כדי להריץ את הדוגמה הזו, צריך להחליף את SPACE_NAME
במזהה של
של המרחב
name
השדה הזה. אפשר לקבל את התעודה המזהה בטלפון
שיטת spaces.list()
או מכתובת ה-URL של המרחב המשותף.
התחלת שרשור או כתיבת תשובה בשרשור
במרחבים משותפים שבהם נעשה שימוש בשרשורים: אפשר להגדיר אם הודעה חדשה תתחיל שרשור או תענה בשרשור קיים.
כברירת מחדל, הודעות שאתם יוצרים באמצעות Chat API מתחילות של שרשור. כדי לזהות את השרשור ולהשיב לו מאוחר יותר, אפשר מפתח ה-thread בבקשה שלך:
- בגוף הבקשה, יש לציין את
thread.threadKey
השדה הזה. - ציון פרמטר השאילתה
messageReplyOption
כדי לבדוק מה יקרה אם המפתח כבר קיים.
כדי ליצור הודעה שעונה על שרשור קיים:
- בגוף הבקשה, כוללים את השדה
thread
. אם המדיניות מוגדרת, אפשר לציין אתthreadKey
שיצרתם. אחרת, צריך להשתמשname
של השרשור. - צריך לציין את פרמטר השאילתה
messageReplyOption
.
הקוד הבא מציג דוגמה לאופן שבו אפליקציית Chat יכול לשלוח הודעת טקסט שמתחילה או משיבה לשרשור מסוים שמזוהה על ידי מפתח של מרחב נתון מטעם משתמש מאומת:
Node.js
Python
Java
Apps Script
כדי להריץ את הדוגמה הזו, מחליפים את מה שכתוב בשדות הבאים:
THREAD_KEY
: מפתח שרשור קיים במרחב המשותף, או כדי ליצור שרשור חדש, שם ייחודי לשרשור.SPACE_NAME
: המזהה של המרחב המשותףname
השדה הזה. אפשר לקבל את התעודה המזהה בטלפון שיטתspaces.list()
או מכתובת ה-URL של המרחב המשותף.
איך נותנים שם להודעה
כדי לאחזר או לציין הודעה בקריאות עתידיות ל-API, אפשר לתת שם להודעה
על ידי הגדרה של השדה messageId
בבקשת messages.create()
.
מתן שם להודעה מאפשר לך לציין את ההודעה בלי שיהיה צורך לשמור את
מזהה שהוקצה על ידי המערכת משם המשאב של ההודעה (שמופיע
name
).
לדוגמה, כדי לאחזר הודעה באמצעות ה-method get()
, צריך להשתמש ב-
שם המשאב שמציין איזו הודעה לאחזר. שם המשאב הוא
בפורמט spaces/{space}/messages/{message}
, כאשר {message}
מייצג
המזהה שהוקצה על ידי המערכת או השם המותאם אישית שהגדרתם כשיצרתם את
הודעה.
כדי לתת שם להודעה, מציינים מזהה מותאם אישית
messageId
בזמן יצירת ההודעה. השדה messageId
מגדיר את הערך של
clientAssignedMessageId
בשדה של המשאב Message
.
אפשר לתת שם להודעה רק כשיוצרים אותה. אין לך אפשרות לתת שם או לשנות מזהה מותאם אישית של הודעות קיימות. המזהה המותאם אישית חייב לעמוד בדרישות הבאות: דרישות:
- מתחיל ב-
client-
. לדוגמה,client-custom-name
הוא מונח חוקי בהתאמה אישית מזהה, אבלcustom-name
הוא לא. - מכיל עד 63 תווים ורק אותיות קטנות, מספרים וגם מקפים.
- הוא ייחודי במרחב המשותף. אפליקציית Chat לא יכולה להשתמש את אותו מזהה מותאם אישית להודעות שונות.
הקוד הבא מציג דוגמה לאופן שבו אפליקציית Chat יכול לשלוח הודעת טקסט עם מזהה למרחב נתון בשם משתמש מאומת:
Node.js
Python
Java
Apps Script
כדי להריץ את הדוגמה הזו, מחליפים את מה שכתוב בשדות הבאים:
SPACE_NAME
: המזהה של המרחב המשותףname
השדה הזה. אפשר לקבל את התעודה המזהה בטלפון שיטתspaces.list()
או מכתובת ה-URL של המרחב המשותף.MESSAGE-ID
: שם ההודעה שמתחילה עםcustom-
. חייב להיות ייחודי משמות אחרים של הודעות שנוצרו על ידי אפליקציית Chat במרחב המשותף שצוין.
פתרון בעיות
כשאפליקציית Google Chat או אפליקציית Google Chat הפונקציה card מחזירה שגיאה, בממשק של Chat מוצגת ההודעה "משהו השתבש". או "לא ניתן לעבד את הבקשה שלך". לפעמים בממשק המשתמש של Chat לא מציגה הודעות שגיאה, אבל אפליקציית Chat או והכרטיס מפיק תוצאה לא צפויה: לדוגמה, הודעה בכרטיס יופיעו.
יכול להיות שלא תופיע הודעת שגיאה בממשק המשתמש של Chat, אבל יש הודעות שגיאה תיאוריות ונתוני יומן זמינים כדי לעזור לכם לתקן שגיאות כשמופעלת רישום שגיאות ביומן של אפליקציות ל-Chat. כדי לקבל עזרה בצפייה: לניפוי באגים ולתיקון שגיאות: פתרון בעיות ותיקון שגיאות ב-Google Chat
נושאים קשורים
- שימוש בכלי ליצירת כרטיסים כדי לעצב ולהציג תצוגה מקדימה של הודעות בכרטיס JSON לאפליקציות צ'אט.
- עיצוב הודעות.
- איך מקבלים פרטים על הודעות?
- הצגת רשימה של ההודעות במרחבים משותפים
- איך מעדכנים את ההודעה?
- איך מוחקים הודעות?
- זיהוי משתמשים בהודעות של Google Chat.
- שליחת הודעות ל-Google Chat באמצעות webhooks נכנסים