במדריך הזה מוסברות הדרכים השונות שבהן האפליקציות של Google Chat יכולות לשלוח הודעות:
- שולחים הודעות טקסט וכרטיסים בזמן אמת על ידי מענה לאינטראקציה של המשתמש.
- שולחים הודעות טקסט וכרטיסים באופן אסינכרוני על ידי קריאה ל-method
create
במשאבMessage
. - להתחיל שרשור הודעות או לענות לו.
- שולחים הודעה ונותנים לה שם.
המשאב Message
מייצג הודעת טקסט או כרטיס ב-Google Chat. אתם יכולים create
, get
, update
או delete
לשלוח הודעות ב-Google Chat API באמצעות קריאה לשיטה המתאימה. במאמר סקירה כללית על הודעות ב-Google Chat תוכלו לקרוא מידע נוסף על הודעות טקסט והודעות בכרטיס.
הגודל המקסימלי של הודעה (כולל טקסט או כרטיסים) הוא 32,000 בייטים. אם ההודעה תחרוג מהגודל הזה, אפליקציית Chat תוכל לשלוח מספר הודעות במקום זאת.
במקום לשלוח קריאה ל-method create
במשאב Message
ב-Google Chat API כדי לשלוח הודעת טקסט או כרטיס באופן אסינכרוני, האפליקציות של Google Chat יכולות גם ליצור הודעות כדי להגיב לאינטראקציות של המשתמשים בזמן אמת. התשובות לאינטראקציות של המשתמשים לא מחייבות אימות ותומכות בסוגים אחרים של הודעות, כולל תיבות דו-שיח אינטראקטיביות ותצוגות מקדימות של קישורים. מידע נוסף מופיע במאמר קבלת אינטראקציות עם אפליקציית Google Chat ושליחת תשובות לגביהן.
דרישות מוקדמות
Node.js
- חשבון Google Workspace עם גישה ל-Google Chat.
- פרויקט ב-Google Cloud שמופעל ומוגדר בו Google Chat API. במאמר איך מפתחים אפליקציות ב-Google Chat מוסבר איך עושים את זה.
- הוגדרה הרשאה לאפליקציית Chat לשליחת הודעות אסינכרוניות. לא נדרשת הרשאה כדי לשלוח הודעות בזמן אמת.
- שליחה של הודעת טקסט תומכת בשתי שיטות ההרשאה הבאות:
- אימות משתמשים עם היקף ההרשאות
chat.messages.create
אוchat.messages
. - אימות אפליקציות עם היקף ההרשאה
chat.bot
.
- אימות משתמשים עם היקף ההרשאות
- כדי לשלוח הודעה בכרטיס, צריך לבצע אימות אפליקציה עם היקף ההרשאה
chat.bot
.
- שליחה של הודעת טקסט תומכת בשתי שיטות ההרשאה הבאות:
Python
- חשבון Google Workspace עם גישה ל-Google Chat.
- Python 3.6 ומעלה
- הכלי pip לניהול חבילות
ספריות הלקוח העדכניות של Google ל-Python. כדי להתקין או לעדכן אותם, מריצים את הפקודה הבאה בממשק שורת הפקודה:
pip3 install --upgrade google-api-python-client google-auth
- פרויקט ב-Google Cloud שמופעל ומוגדר בו Google Chat API. במאמר איך מפתחים אפליקציות ב-Google Chat מוסבר איך עושים את זה.
הוגדרה הרשאה לאפליקציית Chat לשליחת הודעות אסינכרוניות. לא נדרשת הרשאה כדי לשלוח הודעות בזמן אמת.
- שליחה של הודעת טקסט תומכת בשתי שיטות ההרשאה הבאות:
- אימות משתמשים עם היקף ההרשאות
chat.messages.create
אוchat.messages
. - אימות אפליקציות עם היקף ההרשאה
chat.bot
.
- אימות משתמשים עם היקף ההרשאות
- כדי לשלוח הודעה בכרטיס, צריך לבצע אימות אפליקציה עם היקף ההרשאה
chat.bot
.
- שליחה של הודעת טקסט תומכת בשתי שיטות ההרשאה הבאות:
Apps Script
- חשבון Google Workspace עם גישה ל-Google Chat.
- אפליקציית Chat שפורסמה. כדי ליצור אפליקציית Chat, היעזרו בquickstart.
- הוגדרה הרשאה לאפליקציית Chat לשליחת הודעות אסינכרוניות. לא נדרשת הרשאה כדי לשלוח הודעות בזמן אמת.
- שליחה של הודעת טקסט תומכת בשתי שיטות ההרשאה הבאות:
- אימות משתמשים עם היקף ההרשאות
chat.messages.create
אוchat.messages
. - אימות אפליקציות עם היקף ההרשאה
chat.bot
.
- אימות משתמשים עם היקף ההרשאות
- כדי לשלוח הודעה בכרטיס, צריך לבצע אימות אפליקציה עם היקף ההרשאה
chat.bot
.
- שליחה של הודעת טקסט תומכת בשתי שיטות ההרשאה הבאות:
שליחת הודעות טקסט
בקטע הזה מתואר איך לשלוח הודעות טקסט בשתי הדרכים הבאות:
- שליחת הודעת טקסט בזמן אמת באמצעות תגובה לאינטראקציה של משתמש.
- כדי לשלוח הודעת טקסט, מפעילים את Google Chat API באופן אסינכרוני.
שליחת הודעת טקסט בזמן אמת
בדוגמה הזו, אפליקציית Chat יוצרת ושולחת הודעת טקסט בכל פעם שמצרפים אותה למרחב משותף. במאמר איך עוזרים לאנשים ומרחבים משותפים להתחיל לעבוד בצורה מועילה, ריכזנו כאן שיטות מומלצות לקליטת משתמשים.
כדי לשלוח הודעת טקסט כשמשתמש מוסיף את אפליקציית Chat למרחב משותף, אפליקציית Chat מגיבה לאירוע אינטראקציה של ADDED_TO_SPACE
. כדי להשיב בהודעת טקסט לאירועי אינטראקציה מסוג ADDED_TO_SPACE
, צריך להשתמש בקוד הבא:
Node.js
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} event The event object from Chat API.
* @return {Object} Response from the Chat app. An onboarding message that
* introduces the app and helps people get started with it.
*/
exports.onMessage = function onMessage(req, res) {
if (req.method === 'GET' || !req.body.message) {
res.send(
'Hello! This function is meant to be used in a Google Chat space.');
}
// Send an onboarding message when added to a Chat space
if (req.body.type === 'ADDED_TO_SPACE') {
res.json({
'text': 'Hi, Cymbal at your service. I help you manage your calendar
from Google Chat. Take a look at your schedule today by typing
`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
learn what else I can do, type `/help`.'
});
}
};
Apps Script
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} event The event object from Chat API.
* @return {Object} Response from the Chat app. An onboarding message that
* introduces the app and helps people get started with it.
*/
function onAddToSpace(event) {
return {
'text': 'Hi, Cymbal at your service. I help you manage your calendar
from Google Chat. Take a look at your schedule today by typing
`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
what else I can do, type `/help`.'
}
}
דוגמת הקוד מחזירה את הודעת הטקסט הבאה:
שליחה של הודעת טקסט באופן אסינכרוני
בקטע הבא מוסבר איך לשלוח הודעת טקסט באופן אסינכרוני באמצעות אימות אפליקציות ואימות משתמש.
כדי לשלוח הודעת טקסט, מזינים את הפרטים הבאים בבקשה:
- כשמשתמשים באימות אפליקציה, מציינים את היקף ההרשאה
chat.bot
. באימות המשתמש, מציינים את היקף ההרשאהchat.messages.create
. - קוראים ל-method
create
במשאבMessage
.
שליחת הודעת טקסט באמצעות אימות אפליקציה
כך שולחים הודעת טקסט באמצעות אימות אפליקציות:
Python
- בספריית העבודה, יוצרים קובץ בשם
chat_create_text_message_app.py
. צריך לכלול את הקוד הבא ב-
chat_create_text_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) # Create a Chat message. 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', # The message to create. body={'text': 'Hello, world!'} ).execute() print(result)
בקוד, מחליפים את
SPACE
בשם של מרחב משותף, שאפשר לקבל באמצעות ה-methodspaces.list()
ב-Chat API או מכתובת ה-URL של המרחב.בספריית העבודה, יוצרים ומריצים את הדוגמה:
python3 chat_create_text_message_app.py
Chat API מחזיר מופע של Message
שבו מפורט ההודעה שנשלחת.
שליחת הודעת טקסט עם אימות משתמש
כך שולחים הודעת טקסט באמצעות אימות משתמש:
Python
- בספריית העבודה, יוצרים קובץ בשם
chat_create_text_message_user.py
. צריך לכלול את הקוד הבא ב-
chat_create_text_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', # The message to create. body={'text': 'Hello, world!'} ).execute() # Prints details about the created message. print(result) if __name__ == '__main__': main()
בקוד, מחליפים את
SPACE
בשם של מרחב משותף, שאפשר לקבל באמצעות ה-methodspaces.list()
ב-Chat API או מכתובת ה-URL של המרחב.בספריית העבודה, יוצרים ומריצים את הדוגמה:
python3 chat_create_text_message_user.py
Chat API מחזיר מופע של Message
שבו מפורט ההודעה שנשלחת.
שליחת הודעות בכרטיס
בקטע הזה מוסבר איך לשלוח הודעות בכרטיס בשתי הדרכים הבאות:
- שליחת הודעה בכרטיס בזמן אמת על ידי מענה לאינטראקציה של המשתמש.
- כדי לשלוח הודעה בכרטיס, מפעילים את Google Chat API באופן אסינכרוני.
שליחת הודעה בכרטיס בזמן אמת
אפליקציות ל-Chat יכולות ליצור הודעות בכרטיס כדי להגיב לאינטראקציה של המשתמש, למשל, כשמשתמש שולח הודעה לאפליקציית Chat או מוסיף את אפליקציית Chat למרחב המשותף. במאמר קבלה של אירועי אינטראקציה באפליקציית Chat ומענה להזמנות לאירועים כאלה מוסבר איך מגיבים לאינטראקציות של משתמשים.
בדוגמה הבאה משתמש שולח הודעה לאפליקציית Chat, ואפליקציית Chat שולחת לו הודעה בכרטיס עם השם ותמונת הדמות של המשתמש:
Node.js
Python
Apps Script
בדוגמה הזו נשלחת הודעה בכרטיס על ידי החזרת כרטיס JSON של הכרטיס. אפשר גם להשתמש בשירות הכרטיסים של Apps Script.
שליחה של הודעה בכרטיס באופן אסינכרוני
כדי לשלוח הודעה בכרטיס, מעבירים את הבקשה הבאה:
- כשמשתמשים באימות אפליקציה, מציינים את היקף ההרשאה
chat.bot
. אי אפשר לשלוח הודעה בכרטיס באמצעות אימות משתמש. - קוראים ל-method
create
במשאבMessage
.
דוגמה להודעה בכרטיס:
כך שולחים הודעה בכרטיס באמצעות אימות אפליקציה:
Python
- בספריית העבודה, יוצרים קובץ בשם
chat_create_card_message.py
. צריך לכלול את הקוד הבא ב-
chat_create_card_message.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) # Create a Chat message. 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', # The message to create. body= { 'cardsV2': [{ 'cardId': 'createCardMessage', 'card': { 'header': { 'title': 'A card message!', 'subtitle': 'Created with the Chat API', 'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png', 'imageType': 'CIRCLE' }, 'sections': [ { 'widgets': [ { 'buttonList': { 'buttons': [ { 'text': 'Read the docs!', 'onClick': { 'openLink': { 'url': 'https://developers.google.com/chat' } } } ] } } ] } ] } }] } ).execute() print(result)
בקוד, מחליפים את
SPACE
בשם של מרחב משותף, שאפשר לקבל באמצעות ה-methodspaces.list
ב-Chat API או מכתובת ה-URL של המרחב.בספריית העבודה, יוצרים ומריצים את הדוגמה:
python3 chat_create_card_message.py
התחלת שרשור הודעות או מענה להודעות
כדי להתחיל שרשור הודעות, צריך לשלוח הודעה ולהשאיר את השדה thread.name
ריק. המערכת של Google Chat תאוכלס את השדה הזה בזמן יצירת השרשור. אם רוצים להתאים אישית את שם השרשור, אפשר לציין את השדה thread.threadKey
.
כדי לענות לשרשור הודעות, צריך לשלוח הודעה שמציינת את השדה threadKey
או name
של השרשור. אם מישהו או אפליקציית Chat אחרת יצרו את השרשור, תצטרכו להשתמש בשדה thread.name
.
אם לא נמצא שרשור תואם, תוכלו לציין אם הודעה צריכה להתחיל שרשור חדש או לא לפרסם אותה, על ידי הגדרת השדה messageReplyOption
.
אם מגדירים את messageReplyOption
, צריך להגדיר גם את thread.name
או את thread.threadKey
.
כדי להתחיל שרשור או להשיב לו, עם השדה threadKey
מוגדר כ-nameOfThread
:
Python
- בספריית העבודה, יוצרים קובץ בשם
chat_create_message_thread.py
. צריך לכלול את הקוד הבא ב-
chat_create_message_thread.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) # Create a Chat message. 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', # Whether to start a thread or reply to an existing one. # # Required when threading is enabled in a space unless starting a # thread. Ignored in other space types. Threading is enabled when # space.spaceThreadingState is THREADED_MESSAGES. # # REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD replies to an existing thread # if one exists, otherwise it starts a new one. messageReplyOption='REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD', # The message body. body={ # The message to create. 'text': 'Start or reply to another message in a thread!', # The thread to start or reply to. 'thread': { 'threadKey': 'nameOfThread' } } ).execute() print(result)
בקוד, מחליפים את
SPACE
בשם של מרחב משותף, שאפשר לקבל באמצעות ה-methodspaces.list
ב-Chat API או מכתובת ה-URL של המרחב.בספריית העבודה, יוצרים ומריצים את הדוגמה:
python3 chat_create_message_thread.py
Chat API מחזיר מופע של Message
שבו מפורט ההודעה שנשלחת.
איך נותנים שם להודעה
בקטע הזה מוסבר איך לתת שם להודעה באמצעות הגדרת מזהה מותאם אישית
להודעה. אתם יכולים להשתמש במזהים מותאמים אישית כדי לקבל, לעדכן או למחוק הודעות. מזהים מותאמים אישית מאפשרים לציין הודעה בלי שיהיה צורך לשמור את המזהה שהוקצה על ידי המערכת משם המשאב של ההודעה (שמיוצג בשדה name
). שם המשאב נוצר בגוף התגובה כשיוצרים את ההודעה.
לדוגמה, כדי לאחזר הודעה באמצעות ה-method get()
, משתמשים בשם המשאב כדי לציין איזו הודעה לאחזר. הפורמט של שם המשאב הוא spaces/{space}/messages/{message}
, כאשר {message}
מייצג את המזהה שהוקצה על ידי המערכת. אם נתתם להודעה שם, תוכלו להחליף את הערך של {message}
במזהה המותאם אישית.
כדי לתת שם להודעה, צריך לציין מזהה מותאם אישית בשדה messageId
כשיוצרים את ההודעה. השדה messageId
מגדיר את הערך לשדה clientAssignedMessageId
של המשאב Message
.
אפשר לתת שם להודעה רק כשיוצרים אותה. אי אפשר לתת שם או לשנות מזהה מותאם אישית להודעות קיימות. המזהה המותאם אישית צריך לעמוד בדרישות הבאות:
- מתחיל ב-
client-
. לדוגמה,client-custom-name
הוא מזהה מותאם אישית חוקי, אבלcustom-name
לא. - מכיל עד 63 תווים ורק אותיות קטנות, מספרים ומקפים.
- הוא ייחודי במרחב המשותף. אפליקציית Chat לא יכולה להשתמש באותו מזהה מותאם אישית להודעות שונות.
כך שולחים הודעה עם מזהה מותאם אישית:
Python
- בספריית העבודה, יוצרים קובץ בשם
chat_create_named_message.py
. צריך לכלול את הקוד הבא ב-
chat_create_named_message.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) # Create a Chat message with a custom name. 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', # Custom name for the message used to facilitate later operations. messageId='client-NAME', # The message to create. body={'text': 'Hello, world!'} ).execute() print(result)
בקוד, מחליפים את מה שכתוב בשדות הבאים:
SPACE
: מזהה המרחב שבו רוצים לפרסם את ההודעה. אפשר לקבל אותו באמצעות ה-methodspaces.list
ב-Chat API או מכתובת ה-URL של המרחב.NAME
: השם המותאם אישית של ההודעה.
בספריית העבודה, יוצרים ומריצים את הדוגמה:
python3 chat_create_named_message.py
Chat API מחזיר מופע של Message
.
הוספת ווידג'טים אינטראקטיביים בתחתית הודעה
אפשר גם לצרף הודעות באמצעות ווידג'טים של אביזרים. ווידג'טים של אביזרים מופיעים אחרי טקסט או כרטיסים בהודעה. ניתן להשתמש בווידג'טים האלה כדי לעודד משתמשים ליצור אינטראקציה עם ההודעה שלכם בדרכים רבות, ביניהן:
- מה מידת הדיוק או שביעות הרצון של הודעה?
- מדווחים על בעיה בהודעה או באפליקציית Chat.
- פותחים קישור לתוכן קשור, כמו תיעוד.
- אפשר לסגור הודעות דומות מאפליקציית Chat או לסמן אותן לטיפול בהמשך לפרק זמן מסוים.
כדי להוסיף ווידג'טים של אביזרים, צריך לכלול בהודעה את האובייקט accessoryWidgets[]
ולציין AccessoryWidgets
אחד או יותר שרוצים לכלול. ההודעה צריכה להיות גלויה לכל מי שבמרחב המשותף (אי אפשר להוסיף ווידג'טים של אביזרים להודעות פרטיות).
בתמונה הבאה מוצגת אפליקציית Chat שמצרפת הודעת טקסט עם ווידג'טים של אביזרים כדי שהמשתמשים יוכלו לדרג את חוויית השימוש שלהם באפליקציית Chat.
בדוגמת הקוד הבאה מוצג ה-JSON של ההודעה הזו. כשמשתמש לוחץ על אחד מהלחצנים, האינטראקציה מפעילה את הפונקציה המתאימה (כמו 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",
}
}
}
]
}
}
]
שליחת הודעות באופן פרטי
אפליקציות צ'אט יכולות לשלוח הודעות טקסט וכרטיסים באופן פרטי, כך שההודעה תהיה גלויה רק למשתמש אחד במרחב המשותף. כדי לשלוח הודעה בפרטיות, צריך לציין את השדה privateMessageViewer
בהודעה. רק אפליקציות צ'אט יכולות לשלוח הודעות פרטיות. כדי לשלוח הודעה פרטית באופן אסינכרוני, עליכם להשתמש באימות אפליקציות.
מידע נוסף מופיע במאמר שליחת הודעות פרטיות למשתמשי Google Chat.
פתרון בעיות
כשאפליקציית Google Chat או כרטיס מחזירים שגיאה, מוצגת בממשק של Chat ההודעה "משהו השתבש". או "לא ניתן לעבד את הבקשה שלך". לפעמים לא מוצגות הודעות שגיאה בממשק המשתמש של Chat, אבל האפליקציה או הכרטיס של Chat יוצרים תוצאה לא צפויה. למשל, יכול להיות שלא תופיע הודעת כרטיס.
יכול להיות שלא תופיע הודעת שגיאה בממשק המשתמש של Chat, אבל תוכלו להיעזר בהודעות שגיאה תיאוריות ובנתוני היומן שיעזרו לכם לתקן שגיאות כשמופעלת רישום ביומן של שגיאות באפליקציות ל-Chat. למידע נוסף על הצגה, ניפוי באגים ותיקון שגיאות, תוכלו להיעזר במאמר פתרון בעיות ב-Google Chat.
נושאים קשורים
- איך מעצבים הודעות?
- איך מקבלים פרטים על הודעות?
- הצגת רשימה של ההודעות במרחבים משותפים
- איך מעדכנים את ההודעה?
- איך מוחקים הודעות?
- זיהוי משתמשים בהודעות של Google Chat.
- שליחת הודעות ל-Google Chat באמצעות webhooks נכנסים