במדריך הזה מוסברות הדרכים השונות שבהן אפליקציות Google Chat יכולות לשלוח הודעות:
- לשלוח הודעות טקסט וכרטיסים בזמן אמת על ידי שליחת תגובות לאינטראקציה של משתמשים.
- שולחים הודעות טקסט וכרטיסים באופן אסינכרוני על ידי קריאה לשיטה
create
במשאבMessage
. - להתחיל שרשור הודעות או לענות לו.
- שליחת הודעה ומתן שם להודעה.
המשאב Message
מייצג הודעות טקסט או כרטיס ב-Google Chat. אפשר create
, get
, update
או delete
הודעה ב-Google Chat API באמצעות קריאה לשיטות מתאימות. למידע נוסף על הודעות טקסט בכרטיסים, תוכלו לקרוא את הסקירה הכללית על הודעות ב-Google Chat.
גודל ההודעה המקסימלי (כולל טקסט או כרטיסים) הוא 32,000 בייטים. אם אחת מההודעות חורגת מהגודל הזה, אפליקציית Chat תוכל לשלוח כמה הודעות במקום.
במקום להפעיל את השיטה 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
בדוגמה הזו נשלחת הודעת כרטיס על ידי החזרת card 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
). שם המשאב נוצר בגוף התשובה כשיוצרים את ההודעה.
לדוגמה, כדי לאחזר הודעה באמצעות השיטה 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 נכנסים