במדריך הזה מוסבר איך לקרוא ל-API של Google Chat
messages.create()
לביצוע אחת מהפעולות הבאות:
- שליחת הודעות שמכילות טקסט, כרטיסים וווידג'טים אינטראקטיביים.
- שליחת הודעות פרטיות למשתמש מסוים ב-Chat.
- להתחיל שרשור הודעות או לענות לו.
- אפשר לתת שם להודעה כדי שיהיה אפשר לציין אותה ב-Chat API אחר בקשות.
נוסף על קריאה ל-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.
דרישות מוקדמות
Python
- עסק או ארגון חשבון Google Workspace עם גישה אל Google Chat.
- Python 3.6 ומעלה
- הכלי לניהול חבילות pip
- ספריות הלקוח העדכניות של Google. כדי להתקין או לעדכן אותם,
מריצים את הפקודה הבאה בממשק שורת הפקודה:
pip3 install --upgrade google-api-python-client google-auth-oauthlib
- מגדירים את הסביבה:
- יוצרים פרויקט ב-Google Cloud.
- מגדירים את מסך ההסכמה של OAuth.
- מפעילים ומגדירים את Google Chat API עם שם, הסמל והתיאור של אפליקציית Chat.
- יוצרים פרטי כניסה לגישה בהתאם לאופן שבו רוצים לבצע אימות ב-Google Chat API
בקשה:
- כדי לבצע אימות כמשתמשי Chat:
יצירת מזהה לקוח ב-OAuth
פרטי כניסה ולשמור את פרטי הכניסה כקובץ JSON בשם
client_secrets.json
לספרייה המקומית שלך. - כדי לבצע אימות כאפליקציית Chat:
יצירת חשבון שירות
פרטי כניסה ולשמור את פרטי הכניסה כקובץ JSON בשם
credentials.json
.
- כדי לבצע אימות כמשתמשי Chat:
יצירת מזהה לקוח ב-OAuth
פרטי כניסה ולשמור את פרטי הכניסה כקובץ JSON בשם
- בוחרים את היקף ההרשאה בהתאם לאופן שבו רוצים לבצע אימות כמשתמשים או אפליקציית Chat.
- מרחב ב-Google Chat שבו המשתמש המאומת או אפליקציית Chat לשיחות רשומה כמנוי. כדי לבצע אימות בתור אפליקציית Chat, מוסיפים את להשתמש באפליקציית Chat במרחב המשותף.
שליחת הודעת טקסט בשם משתמש
בקטע הזה מוסבר איך לשלוח הודעות בשם משתמש באמצעות אימות משתמש. באימות משתמש, תוכן ההודעה יכול להכיל רק טקסט וחייבים להשמיט תכונות של העברת הודעות שזמינות רק ללקוחות. אפליקציות צ'אט, כולל ממשקי כרטיסים וווידג'טים אינטראקטיביים.
כדי להפעיל את messages.create()
באמצעות אימות משתמש, צריך לציין את
השדות הבאים בבקשה:
- היקף ההרשאה
שתומך באימות משתמשים בשיטה הזו. הדוגמה הבאה משתמשת
ההיקף
chat.messages.create
. - המשאב
Space
שבו שרוצים לפרסם את ההודעה. המשתמש המאומת חייב להיות חבר המרחב המשותף. Message
של המשאבים שצריך ליצור. כדי להגדיר את תוכן ההודעה, עליך לכלול אתtext
השדה הזה.
אפשר לכלול גם את הפרטים הבאים:
- השדה
messageId
, שמאפשר נותנים שם להודעה כדי להשתמש בה בבקשות API אחרות. - השדות
thread.threadKey
ו-messageReplyOption
כדי להתחיל שרשורים או להשיב עליהם. אם לא מוסיפים שימוש בשרשור, המערכת תתעלם מהשדה הזה.
כדי לשלוח הודעת טקסט בשם משתמש, מבצעים את השלבים הבאים:
Python
- בספריית העבודה, יוצרים קובץ בשם
chat_create_message_user.py
צריך לכלול את הקוד הבא ב-
chat_create_message_user.py
:import os.path from google.auth.transport.requests import Request from google.oauth2.credentials import Credentials from google_auth_oauthlib.flow import InstalledAppFlow from googleapiclient.discovery import build from googleapiclient.errors import HttpError # Define your app's authorization scopes. # When modifying these scopes, delete the file token.json, if it exists. SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"] def main(): ''' Authenticates with Chat API via user credentials, then creates a text message in a Chat space. ''' # Start with no credentials. creds = None # Authenticate with Google Workspace # and get user authorization. flow = InstalledAppFlow.from_client_secrets_file( 'client_secrets.json', SCOPES) creds = flow.run_local_server() # Build a service endpoint for Chat API. chat = build('chat', 'v1', credentials=creds) # Use the service endpoint to call Chat API. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # Optional. Sets custom ID for the message to use in other requests. messageId='client-myfirstusermessage', # The text message to create. body={ 'text': '👋 🌎Hello world! Text messages can contain things like:\n\n' + '* Hyperlinks 🔗\n' + '* Emojis 😄🎉\n' + '* Mentions of other Chat users `@` \n\n' 'For details, see the <https://developers.google.com/workspace/chat/format-messages|Chat API developer documentation>.' } ).execute() # Prints details about the created message. print(result) if __name__ == '__main__': main()
מחליפים את
SPACE
במזהה של המרחב המשותףname
השדה הזה. אפשר לקבל את התעודה המזהה בטלפון שיטתspaces.list()
או מכתובת ה-URL של המרחב המשותף.בספריית העבודה, יוצרים ומריצים את הדוגמה:
python3 chat_create_message_user.py
אם מופיעה כתובת URL, צריך לפתוח את כתובת ה-URL כדי לאשר את אפליקציית Chat בהתאם להיקף שהשתמשתם בו בקשה.
אפליקציית Chat יוצרת את ההודעה,
משתמש מפרסם את ההודעה במרחב. בממשק שורת הפקודה,
Chat API מחזיר את המופע של
משאב Message
.
שליחת הודעה בתור אפליקציית Chat
בקטע הזה מוסבר איך לשלוח הודעות שמכילות טקסט, כרטיסים ווידג'טים של אביזרים אינטראקטיביים באמצעות אימות אפליקציות.
כדי להפעיל את messages.create()
באמצעות אימות אפליקציות, צריך לציין
השדות הבאים בבקשה:
chat.bot
היקף ההרשאה.- המשאב
Space
שבו שרוצים לפרסם את ההודעה. אפליקציית Chat צריכה להיות משתמש במרחב המשותף. Message
של המשאבים שצריך ליצור. כדי להגדיר את תוכן ההודעה, אפשר לכלול טקסט עשיר (text
), ממשק כרטיס אחד או יותר (cardsV2
), או לשניהם.
אפשר לכלול גם את הפרטים הבאים:
- השדה
accessoryWidgets
שיש לכלול לחצנים אינטראקטיביים בחלק התחתון של ההודעה. - השדה
privateMessageViewer
כדי לשלוח את ההודעה באופן פרטי למשתמש מסוים. - השדה
messageId
, שמאפשר נותנים שם להודעה כדי להשתמש בה בבקשות API אחרות. - השדות
thread.threadKey
ו-messageReplyOption
כדי להתחיל שרשורים או להשיב עליהם. אם לא מוסיפים שימוש בשרשור, המערכת תתעלם מהשדה הזה.
הגודל המקסימלי של הודעה (כולל טקסט או כרטיסים) הוא 32,000 בייטים. כדי לשלוח הודעה גדולה יותר מהגודל הזה, צריך להשתמש באפליקציית Chat צריך לשלוח מספר הודעות.
כדי לשלוח הודעה שפורסמה כאפליקציית Chat שמכילה טקסט, כרטיס ולחצן שניתן ללחוץ עליו בתחתית ההודעה, יש לבצע את השלבים הבאים:
Python
- בספריית העבודה, יוצרים קובץ בשם
chat_create_message_app.py
צריך לכלול את הקוד הבא ב-
chat_create_message_app.py
:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Specify the Chat space where the message is posted. Obtain the ID # from the resource name, or from the space's URL. SPACE = 'spaces/SPACE' # Create a Chat message. result = chat.spaces().messages().create( # The Chat space. parent=SPACE, # Optional. Sets custom ID for the message to use in other requests. messageId='client-myfirstappmessage', # The message to create with text, a card, and a button at the # bottom of the message. body= { 'text': '👋 🌎Hello world! I created this message by calling the Chat API\'s `messages.create()` method.', 'cardsV2': [{ 'cardId': 'myCardId', 'card': { 'header': { 'title': 'About this message', 'imageUrl': 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg', 'imageType': 'CIRCLE' }, "sections": [ { "header": "Contents", "widgets": [ { "textParagraph": { "text": "🔡 <b>Text</b> which can include hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️." }}, { "textParagraph": { "text": "🖼️ A <b>card</b> to display visual elements and request information such as text 🔤, dates and times 📅, and selections ☑️." }}, { "textParagraph": { "text": "👉🔘 An <b>accessory widget</b> which adds a button to the bottom of a message." }}, ] }, { "header": "What's next", "collapsible": True, "widgets": [ { "textParagraph": { "text": "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>." }}, { "textParagraph": { "text": "🔄 <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/patch'>Update</a> or ❌ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/delete'>delete</a> the message." }}, { "textParagraph": { "text": '💡 <b>Pro tip</b>: To specify the message in other API requests, use its custom name: <i>' + SPACE + '/messages/client-myfirstappmessage</i>.' }} ] } ]} }], "accessoryWidgets": [ { "buttonList": { "buttons": [ { "text": "View documentation", "altText": "Opens a new browser tab and navigates to the Google Chat developer documentation website.", "icon": { "material_icon": { "name": "link" } }, "onClick": { "openLink": { "url": "https://developers.google.com/workspace/chat/create-messages" } } } ] } } ] } ).execute() print(result)
מחליפים את
SPACE
במזהה של המרחב המשותףname
השדה הזה. אפשר לקבל את התעודה המזהה בטלפון שיטתspaces.list()
או מכתובת ה-URL של המרחב המשותף.בספריית העבודה, יוצרים ומריצים את הדוגמה:
python3 chat_create_message_app.py
אפליקציית Chat יוצרת ומפרסמת את ההודעה
המרחב המשותף. בממשק שורת הפקודה, ה-Chat API מחזיר
של המכונה החדשה
משאב Message
.
הוספת ווידג'טים אינטראקטיביים בתחתית הודעה
בדוגמת הקוד שבקטע הקודם, בהודעה שמופיעה באפליקציית Chat מוצג לחצן שאפשר ללחוץ עליו בחלק התחתון של ההודעה, נקרא ווידג'ט האביזר. ווידג'טים של אביזרים מופיעים אחרי טקסט או כרטיסים בהודעה. אפשר להשתמש בווידג'טים האלה כדי להציג למשתמשים לקיים אינטראקציה עם המסר שלכם בדרכים רבות, כולל:
- מה מידת הדיוק או שביעות הרצון של הודעה?
- מדווחים על בעיה בהודעה או באפליקציית Chat.
- פותחים קישור לתוכן קשור, כמו תיעוד.
- סגירה של הודעות דומות או סימון שהן לטיפול בהמשך באפליקציית Chat לתקופת זמן ספציפית.
כדי להוסיף ווידג'טים של אביזרים, צריך לכלול את
accessoryWidgets[]
בשדה בגוף הבקשה ולציין ווידג'ט אחד או יותר שרוצים
לכלול.
בתמונה הבאה מוצגת אפליקציית Chat הודעת טקסט עם ווידג'טים של אביזרים כדי שהמשתמשים יוכלו לדרג את החוויה שלהם באמצעות אפליקציית Chat.
![ווידג'ט האביזר.](https://developers.google.cn/static/workspace/chat/images/message-accessory-widgets-reference.png?authuser=0000&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.
כדי לשלוח הודעה באופן פרטי, חובה להשמיט את הפרטים הבאים בבקשה:
התחלת שרשור או כתיבת תשובה בשרשור
במרחבים משותפים שבהם נעשה שימוש בשרשורים: אפשר להגדיר אם הודעה חדשה תתחיל שרשור או תענה בשרשור קיים.
כברירת מחדל, הודעות שאתם יוצרים באמצעות Chat API מתחילות של שרשור. כדי לזהות את השרשור ולהשיב לו מאוחר יותר, אפשר מפתח ה-thread בבקשה שלך:
- בגוף הבקשה, יש לציין את
thread.threadKey
השדה הזה. - ציון פרמטר השאילתה
messageReplyOption
כדי לבדוק מה יקרה אם המפתח כבר קיים.
כדי ליצור הודעה שעונה על שרשור קיים:
- בגוף הבקשה, כוללים את השדה
thread
. אם המדיניות מוגדרת, אפשר לציין אתthreadKey
שיצרתם. אחרת, צריך להשתמשname
של השרשור. - צריך לציין את פרמטר השאילתה
messageReplyOption
.
קובץ ה-JSON הבא מציג דוגמה לגוף הבקשה של הודעת טקסט
מתחיל שרשור או משיב בשרשור עם המפתח helloWorldThread
:
{
'thread': {
'threadKey': 'helloWorldThread',
},
'text': '👋 🌎Hello world!'
}
איך נותנים שם להודעה
כדי לאחזר או לציין הודעה בקריאות עתידיות ל-API, אפשר לתת שם להודעה
על ידי הגדרה של השדה messageId
בבקשת messages.create()
.
מתן שם להודעה מאפשר לך לציין את ההודעה בלי שיהיה צורך לשמור את
מזהה שהוקצה על ידי המערכת משם המשאב של ההודעה (שמופיע
name
).
לדוגמה, כדי לאחזר הודעה באמצעות ה-method get()
, צריך להשתמש ב-
שם המשאב שמציין איזו הודעה לאחזר. שם המשאב הוא
בפורמט spaces/{space}/messages/{message}
, כאשר {message}
מייצג
המזהה שהוקצה על ידי המערכת או השם המותאם אישית שהגדרתם כשיצרתם את
הודעה.
כדי לתת שם להודעה, מציינים מזהה מותאם אישית
messageId
בזמן יצירת ההודעה. השדה messageId
מגדיר את הערך של
clientAssignedMessageId
בשדה של המשאב Message
.
אפשר לתת שם להודעה רק כשיוצרים אותה. אין לך אפשרות לתת שם או לשנות מזהה מותאם אישית של הודעות קיימות. המזהה המותאם אישית חייב לעמוד בדרישות הבאות: דרישות:
- מתחיל ב-
client-
. לדוגמה,client-custom-name
הוא מונח חוקי בהתאמה אישית מזהה, אבלcustom-name
הוא לא. - מכיל עד 63 תווים ורק אותיות קטנות, מספרים וגם מקפים.
- הוא ייחודי במרחב המשותף. אפליקציית Chat לא יכולה להשתמש את אותו מזהה מותאם אישית להודעות שונות.
פתרון בעיות
כשאפליקציית Google Chat או אפליקציית Google Chat הפונקציה card מחזירה שגיאה, בממשק של Chat מוצגת ההודעה "משהו השתבש". או "לא ניתן לעבד את הבקשה שלך". לפעמים בממשק המשתמש של Chat לא מציגה הודעות שגיאה, אבל אפליקציית Chat או והכרטיס מפיק תוצאה לא צפויה: לדוגמה, הודעה בכרטיס יופיעו.
יכול להיות שלא תופיע הודעת שגיאה בממשק המשתמש של Chat, אבל יש הודעות שגיאה תיאוריות ונתוני יומן זמינים כדי לעזור לכם לתקן שגיאות כשמופעלת רישום שגיאות ביומן של אפליקציות ל-Chat. לקבלת עזרה בצפייה, לניפוי באגים ולתיקון שגיאות: פתרון בעיות ותיקון שגיאות ב-Google Chat
נושאים קשורים
- שימוש בכלי ליצירת כרטיסים כדי לעצב ולהציג תצוגה מקדימה של הודעות בכרטיס JSON לאפליקציות צ'אט.
- עיצוב הודעות.
- איך מקבלים פרטים על הודעות?
- הצגת רשימה של ההודעות במרחבים משותפים
- איך מעדכנים את ההודעה?
- איך מוחקים הודעות?
- זיהוי משתמשים בהודעות של Google Chat.
- שליחת הודעות ל-Google Chat באמצעות webhooks נכנסים