במדריך הזה מוסבר איך להשתמש בשיטה
create()
במשאב Message
של Google Chat API כדי לבצע את הפעולות הבאות:
- שליחת הודעות שמכילות טקסט, כרטיסים ווידג'טים אינטראקטיביים.
- שליחת הודעות באופן פרטי למשתמש ספציפי ב-Chat.
- להתחיל שרשור או לענות לשרשור.
- נותנים שם להודעה, כדי שתוכלו לציין אותה בבקשות אחרות ל-Chat API.
הגודל המקסימלי של ההודעה (כולל טקסט או כרטיסים) הוא 32,000 בייטים. כדי לשלוח הודעה שחורגת מהגודל הזה, אפליקציית Chat צריכה לשלוח במקום זאת כמה הודעות.
בנוסף לקריאה ל-Chat API כדי ליצור הודעות, אפליקציות ל-Chat יכולות ליצור ולשלוח הודעות בתגובה לאינטראקציות של משתמשים, כמו פרסום הודעת פתיחה אחרי שמשתמש מוסיף את האפליקציה ל-Chat למרחב. כשמשיבים לאינטראקציות, אפליקציות צ'אט יכולות להשתמש בסוגים אחרים של תכונות העברת הודעות, כולל דיאלוגים אינטראקטיביים וממשקי תצוגה מקדימה של קישורים. כדי לענות למשתמש, אפליקציית Chat מחזירה את ההודעה באופן סינכרוני, בלי לקרוא ל-Chat API. כדי לקבל מידע על שליחת הודעות בתגובה לאינטראקציות, אפשר לעיין במאמר קבלת תגובות לאינטראקציות עם אפליקציית Google Chat.
איך מוצגות ב-Chat הודעות שנוצרו באמצעות Chat API
אפשר להתקשר לשיטת create()
באמצעות אימות אפליקציה ואימות משתמש.
ב-Chat, השיוך של שולח ההודעה משתנה בהתאם לסוג האימות שבו אתם משתמשים.
כשמבצעים אימות כאפליקציית Chat, ההודעה נשלחת מאפליקציית Chat.
App
ב-Chat.כשמבצעים אימות כמשתמש, אפליקציית Chat שולחת את ההודעה בשם המשתמש. בנוסף, ב-Chat מופיע שם האפליקציה כדי לציין שהיא שלחה את ההודעה.
סוג האימות קובע גם אילו תכונות וממשקים של הודעות אפשר לכלול בהודעה. באמצעות אימות אפליקציות, אפליקציות ל-Chat יכולות לשלוח הודעות שמכילות טקסט עשיר, ממשקים מבוססי-כרטיסים ווידג'טים אינטראקטיביים. מכיוון שמשתמשי Chat יכולים לשלוח רק טקסט בהודעות שלהם, אפשר לכלול רק טקסט כשיוצרים הודעות באמצעות אימות משתמש. מידע נוסף על תכונות ההודעות שזמינות ב-Chat API זמין בסקירה הכללית על הודעות ב-Google Chat.
במדריך הזה מוסבר איך להשתמש בכל אחד מסוגי האימות כדי לשלוח הודעה באמצעות Chat API.
דרישות מוקדמות
Node.js
- חשבון Google Workspace במהדורת Business או Enterprise עם גישה ל-Google Chat.
- מגדירים את הסביבה:
- יוצרים פרויקט ב-Google Cloud.
- הגדרת מסך ההסכמה של OAuth.
- מפעילים ומגדירים את Google Chat API עם שם, סמל ותיאור לאפליקציית Chat.
- מתקינים את ספריית הלקוח של Cloud ל-Node.js.
- יוצרים פרטי גישה בהתאם לאופן שבו רוצים לבצע אימות בבקשה של Google Chat API:
- כדי לבצע אימות כמשתמש ב-Chat, יוצרים פרטי כניסה של מזהה לקוח OAuth ושומרים אותם כקובץ JSON בשם
credentials.json
בספרייה המקומית. - כדי לבצע אימות כאפליקציית Chat, יוצרים פרטי כניסה לחשבון שירות ושומרים אותם כקובץ JSON בשם
credentials.json
.
- כדי לבצע אימות כמשתמש ב-Chat, יוצרים פרטי כניסה של מזהה לקוח OAuth ושומרים אותם כקובץ JSON בשם
- בוחרים היקף הרשאה בהתאם לאופן שבו רוצים לבצע אימות – כמשתמש או כאפליקציית Chat.
- מרחב ב-Google Chat שמשתמש מאומת או אפליקציית Chat שמתקשרת חברים בו. כדי לאמת את עצמכם כאפליקציית Chat, צריך להוסיף את אפליקציית Chat למרחב.
Python
- חשבון Google Workspace במהדורת Business או Enterprise עם גישה ל-Google Chat.
- מגדירים את הסביבה:
- יוצרים פרויקט ב-Google Cloud.
- הגדרת מסך ההסכמה של OAuth.
- מפעילים ומגדירים את Google Chat API עם שם, סמל ותיאור לאפליקציית Chat.
- מתקינים את ספריית הלקוח של Cloud ל-Python.
- יוצרים פרטי גישה בהתאם לאופן שבו רוצים לבצע אימות בבקשה של Google Chat API:
- כדי לבצע אימות כמשתמש ב-Chat, יוצרים פרטי כניסה של מזהה לקוח OAuth ושומרים אותם כקובץ JSON בשם
credentials.json
בספרייה המקומית. - כדי לבצע אימות כאפליקציית Chat, יוצרים פרטי כניסה לחשבון שירות ושומרים אותם כקובץ JSON בשם
credentials.json
.
- כדי לבצע אימות כמשתמש ב-Chat, יוצרים פרטי כניסה של מזהה לקוח OAuth ושומרים אותם כקובץ JSON בשם
- בוחרים היקף הרשאה בהתאם לאופן שבו רוצים לבצע אימות – כמשתמש או כאפליקציית Chat.
- מרחב ב-Google Chat שמשתמש מאומת או אפליקציית Chat שמתקשרת חברים בו. כדי לאמת את עצמכם כאפליקציית Chat, צריך להוסיף את אפליקציית Chat למרחב.
Java
- חשבון Google Workspace במהדורת Business או Enterprise עם גישה ל-Google Chat.
- מגדירים את הסביבה:
- יוצרים פרויקט ב-Google Cloud.
- הגדרת מסך ההסכמה של OAuth.
- מפעילים ומגדירים את Google Chat API עם שם, סמל ותיאור לאפליקציית Chat.
- מתקינים את ספריית הלקוח של Cloud ל-Java.
- יוצרים פרטי גישה בהתאם לאופן שבו רוצים לבצע אימות בבקשה של Google Chat API:
- כדי לבצע אימות כמשתמש ב-Chat, יוצרים פרטי כניסה של מזהה לקוח OAuth ושומרים אותם כקובץ JSON בשם
credentials.json
בספרייה המקומית. - כדי לבצע אימות כאפליקציית Chat, יוצרים פרטי כניסה לחשבון שירות ושומרים אותם כקובץ JSON בשם
credentials.json
.
- כדי לבצע אימות כמשתמש ב-Chat, יוצרים פרטי כניסה של מזהה לקוח OAuth ושומרים אותם כקובץ JSON בשם
- בוחרים היקף הרשאה בהתאם לאופן שבו רוצים לבצע אימות – כמשתמש או כאפליקציית Chat.
- מרחב ב-Google Chat שמשתמש מאומת או אפליקציית Chat שמתקשרת חברים בו. כדי לאמת את עצמכם כאפליקציית Chat, צריך להוסיף את אפליקציית Chat למרחב.
Apps Script
- חשבון Google Workspace במהדורת Business או Enterprise עם גישה ל-Google Chat.
- מגדירים את הסביבה:
- יוצרים פרויקט ב-Google Cloud.
- הגדרת מסך ההסכמה של OAuth.
- מפעילים ומגדירים את Google Chat API עם שם, סמל ותיאור לאפליקציית Chat.
- יוצרים פרויקט עצמאי של Apps Script ומפעילים את שירות Chat מתקדם.
- במדריך הזה, חובה להשתמש באימות משתמשים או באפליקציות. כדי לבצע אימות כאפליקציית Chat, צריך ליצור פרטי כניסה לחשבון שירות. במאמר אימות והרשאה כאפליקציה ל-Google Chat מוסבר איך לעשות זאת.
- בוחרים היקף הרשאה בהתאם לאופן שבו רוצים לבצע אימות – כמשתמש או כאפליקציית Chat.
- מרחב ב-Google Chat שמשתמש מאומת או אפליקציית Chat שמתקשרת חברים בו. כדי לאמת את עצמכם כאפליקציית Chat, צריך להוסיף את אפליקציית Chat למרחב.
שליחת הודעה בשם אפליקציית Chat
בקטע הזה מוסבר איך לשלוח הודעות שמכילות טקסט, כרטיסים ווידג'טים אינטראקטיביים של אביזרים באמצעות אימות אפליקציות.
כדי להתקשר לשיטת CreateMessage()
באמצעות אימות אפליקציה, צריך לציין את השדות הבאים בבקשה:
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
של המרחב. אפשר לקבל את המזהה על ידי הפעלת השיטה ListSpaces()
או מכתובת ה-URL של המרחב.
הוספת ווידג'טים אינטראקטיביים לחלק התחתון של ההודעה
בדוגמת הקוד הראשונה במדריך הזה, ההודעה באפליקציית הצ'אט כוללת כפתור שאפשר ללחוץ עליו בתחתית ההודעה, שנקרא ווידג'ט של אביזר. ווידג'טים של אביזרים מופיעים אחרי כל טקסט או כרטיסים בהודעה. אתם יכולים להשתמש בווידג'טים האלה כדי לעודד את המשתמשים ליצור אינטראקציה עם המסר שלכם בדרכים רבות, כולל:
- לדרג את הדיוק או את רמת שביעות הרצון מההודעה.
- מדווחים על בעיה בהודעה או באפליקציית Chat.
- פותחים קישור לתוכן קשור, כמו תיעוד.
- אפשר לסגור או להשהות הודעות דומות מאפליקציית Chat למשך תקופה מסוימת.
כדי להוסיף ווידג'טים של אביזרים, צריך לכלול את השדה accessoryWidgets[]
בגוף הבקשה ולציין ווידג'ט אחד או יותר שרוצים לכלול.
בתמונה הבאה מוצגת אפליקציית Chat שמצרפת לווידג'טים של אביזרים להודעת טקסט, כדי שהמשתמשים יוכלו לדרג את החוויה שלהם עם אפליקציית Chat.

בדוגמה הבאה מוצג גוף הבקשה שיוצרת הודעת טקסט עם שני לחצני אביזר. כשמשתמש לוחץ על לחצן, הפונקציה המתאימה (למשל 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, מוצגת תווית בהודעה שמציינת שהיא גלויה רק למשתמש.
כדי לשלוח הודעה באופן פרטי באמצעות Chat API, מציינים את השדה privateMessageViewer
בגוף הבקשה. כדי לציין את המשתמש, מגדירים את הערך למשאב User
שמייצג את המשתמש ב-Chat. אפשר גם להשתמש בשדה name
של מקור User
, כמו בדוגמה הבאה:
{
text: "Hello private world!",
privateMessageViewer: {
name: "users/USER_ID"
}
}
כדי להשתמש בדוגמה הזו, מחליפים את USER_ID
במזהה ייחודי של המשתמש, כמו 12345678987654321
או hao@cymbalgroup.com
. מידע נוסף על ציון משתמשים זמין במאמר זיהוי וציון של משתמשי Google Chat.
כדי לשלוח הודעה באופן פרטי, צריך להשמיט מהבקשה את הפרטים הבאים:
שליחת הודעת טקסט בשם משתמש
בקטע הזה מוסבר איך לשלוח הודעות בשם משתמש באמצעות אימות משתמש. באימות משתמשים, תוכן ההודעה יכול לכלול רק טקסט ואסור לכלול תכונות של העברת הודעות שזמינות רק באפליקציות ל-Chat, כולל ממשקי כרטיסים ווידג'טים אינטראקטיביים.
כדי לקרוא לשיטה CreateMessage()
באמצעות אימות משתמשים, צריך לציין את השדות הבאים בבקשה:
- היקף הרשאה שתומך באימות משתמשים עבור השיטה הזו. בדוגמה הבאה נעשה שימוש בהיקף
chat.messages.create
. - מקור
Space
שבו רוצים לפרסם את ההודעה. המשתמש המאומת צריך להיות חבר במרחב. - משאב
Message
שצריך ליצור. כדי להגדיר את תוכן ההודעה, צריך לכלול את השדהtext
.
אפשר גם לכלול את הפרטים הבאים:
- השדה
messageId
, שמאפשר לתת שם להודעה כדי להשתמש בה בבקשות אחרות ל-API. - השדות
thread.threadKey
ו-messageReplyOption
כדי להתחיל שרשור או לענות לשרשור. אם במרחב אין שרשורים, המערכת מתעלמת מהשדה הזה.
בדוגמת הקוד הבאה אפשר לראות איך אפליקציית Chat יכולה לשלוח הודעת טקסט במרחב נתון בשם משתמש מאומת:
Node.js
Python
Java
Apps Script
כדי להריץ את הדוגמה הזו, מחליפים את SPACE_NAME
במזהה מהשדה name
של המרחב. אפשר לקבל את המזהה על ידי הפעלת השיטה ListSpaces()
או מכתובת ה-URL של המרחב.
התחלת שרשור או הוספת תשובה לשרשור
במרחבים שבהם השיחות מחולקות לשרשורים, אתם יכולים לציין אם הודעה חדשה תתחיל שרשור או תהיה תשובה לשרשור קיים.
כברירת מחדל, הודעות שנוצרות באמצעות Chat API מתחילות שרשור חדש. כדי שתוכלו לזהות את השרשור ולהשיב לו מאוחר יותר, אתם יכולים לציין מפתח שרשור בבקשה:
- בגוף הבקשה, מציינים את השדה
thread.threadKey
. - מציינים את פרמטר השאילתה
messageReplyOption
כדי לקבוע מה קורה אם המפתח כבר קיים.
כדי ליצור הודעה שמוסיפה תשובה לשרשור קיים:
- בגוף הבקשה, מציינים את השדה
thread
. אם הגדרתם, תוכלו לציין אתthreadKey
שיצרתם. בכל מקרה אחר, צריך להשתמש בname
של השרשור. - מציינים את פרמטר השאילתה
messageReplyOption
.
הקוד הבא מציג דוגמה לאופן שבו אפליקציית Chat יכולה לשלוח הודעת טקסט שמתחילה או מגיבה לשרשור נתון שמזוהה על ידי מפתח של מרחב נתון בשם משתמש מאומת:
Node.js
Python
Java
Apps Script
כדי להריץ את הדוגמה הזו, מחליפים את הערכים הבאים:
-
THREAD_KEY
: מפתח קיים של השרשור במרחב, או שם ייחודי לשרשור כדי ליצור שרשור חדש. -
SPACE_NAME
: המזהה מהשדהname
של המרחב. אפשר לקבל את המזהה על ידי הפעלת השיטהListSpaces()
או מכתובת ה-URL של המרחב.
איך נותנים שם להודעה
כדי לאחזר או לציין הודעה בקריאות עתידיות ל-API, אפשר לתת שם להודעה על ידי הגדרת השדה messageId
בבקשה.
כשנותנים שם להודעה, אפשר לציין את ההודעה בלי לשמור את המזהה שהמערכת הקצתה לה מתוך שם המשאב של ההודעה (שמוצג בשדה name
).
לדוגמה, כדי לאחזר הודעה באמצעות השיטה 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
של המרחב. אפשר לקבל את המזהה על ידי הפעלת השיטהListSpaces()
או מכתובת ה-URL של המרחב. -
MESSAGE-ID
: שם ההודעה שמתחיל ב-custom-
. השם חייב להיות ייחודי ושונה משמות של הודעות אחרות שנוצרו על ידי אפליקציית Chat במרחב שצוין.
פתרון בעיות
כשמוחזרת שגיאה מאפליקציית Google Chat או מכרטיס, מוצגת בממשק של Chat ההודעה 'משהו השתבש'. או 'לא ניתן לעבד את הבקשה שלך'. לפעמים בממשק המשתמש של Chat לא מוצגת הודעת שגיאה, אבל אפליקציית Chat או הכרטיס מפיקים תוצאה לא צפויה. לדוגמה, יכול להיות שהודעה בכרטיס לא תופיע.
יכול להיות שלא תוצג הודעת שגיאה בממשק המשתמש של Chat, אבל אם הפעלתם את רישום השגיאות באפליקציות של Chat, תוכלו לראות הודעות שגיאה תיאוריות ונתוני יומן שיעזרו לכם לתקן את השגיאות. לקבלת עזרה בצפייה בשגיאות, באיתור באגים ובתיקון שלהן, אפשר לעיין במאמר פתרון בעיות ב-Google Chat.
נושאים קשורים
- משתמשים בכלי ליצירת כרטיסים כדי לעצב ולראות תצוגה מקדימה של הודעות כרטיס JSON לאפליקציות ל-Chat.
- עיצוב הודעות
- איך מקבלים פרטים על הודעה
- הצגת רשימה של ההודעות במרחב.
- איך מעדכנים הודעה
- מחיקת הודעה
- זיהוי משתמשים בהודעות ב-Google Chat
- שליחת הודעות ל-Google Chat באמצעות webhooks נכנסים.