במדריך הזה מוסבר מהן הדרכים השונות שבהן האפליקציות של Google Chat יכולות לשלוח הודעות:
- שליחת הודעות טקסט וכרטיסים בזמן אמת באמצעות מענה למשתמש אינטראקציה חוזרת.
- שליחת הודעות טקסט וכרטיסים באופן אסינכרוני על ידי הפעלה של השיטה
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 Chat. איך יוצרים אפליקציה ב-Chat באמצעות שירות HTTP, השלימו את מדריך למתחילים.
- הוגדרה הרשאה לשליחה של אפליקציית Chat
הודעות אסינכרוניות. לא צריך להגדיר הרשאה כדי לשלוח
הודעות בזמן אמת.
- בתהליך שליחה של
הודעת טקסט
תומכת בשתי שיטות ההרשאה הבאות:
- אימות משתמשים
עם ההרשאה
chat.messages.create
אוchat.messages
היקף. - אימות אפליקציות
עם היקף ההרשאה
chat.bot
.
- אימות משתמשים
עם ההרשאה
- בתהליך שליחה של
הודעה בכרטיס
נדרש
אימות אפליקציות
עם היקף ההרשאה
chat.bot
.
- בתהליך שליחה של
הודעת טקסט
תומכת בשתי שיטות ההרשאה הבאות:
Python
- אפליקציית Google Chat. איך יוצרים אפליקציה ב-Chat באמצעות שירות HTTP, השלימו את מדריך למתחילים.
- הוגדרה הרשאה לשליחה של אפליקציית Chat
הודעות אסינכרוניות. לא צריך להגדיר הרשאה כדי לשלוח
הודעות בזמן אמת.
- בתהליך שליחה של
הודעת טקסט
תומכת בשתי שיטות ההרשאה הבאות:
- אימות משתמשים
עם ההרשאה
chat.messages.create
אוchat.messages
היקף. - אימות אפליקציות
עם היקף ההרשאה
chat.bot
.
- אימות משתמשים
עם ההרשאה
- שליחת
הודעה בכרטיס
נדרש
אימות אפליקציות
עם היקף ההרשאה
chat.bot
.
- בתהליך שליחה של
הודעת טקסט
תומכת בשתי שיטות ההרשאה הבאות:
Apps Script
- אפליקציית Google Chat. איך יוצרים אפליקציה ב-Chat ב-Apps Script, השלימו את מדריך למתחילים.
- הוגדרה הרשאה לשליחה של אפליקציית 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
. - קוראים לפונקציה
אמצעי תשלום אחד (
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
בשם של מרחב משותף. שאפשר לקבל אמצעי תשלום אחד (spaces.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
בשם של מרחב משותף. שאפשר לקבלspaces.list()
method ב 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
. אי אפשר שליחת הודעת כרטיס עם אימות משתמש. - קוראים לפונקציה
אמצעי תשלום אחד (
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
בשם של מרחב משותף. שאפשר לקבל אמצעי תשלום אחד (spaces.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
בשם של מרחב משותף. שאפשר לקבל אמצעי תשלום אחד (spaces.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
: המזהה של המרחב המשותף שאליו רוצים לפרסם את ההודעה, שאפשר לקבל אמצעי תשלום אחד (spaces.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 או אפליקציית Google Chat הפונקציה card מחזירה שגיאה, בממשק של Chat מוצגת ההודעה "משהו השתבש". או "לא ניתן לעבד את הבקשה שלך". לפעמים בממשק המשתמש של Chat לא מציגה הודעות שגיאה, אבל אפליקציית Chat או והכרטיס מפיק תוצאה לא צפויה: לדוגמה, הודעה בכרטיס יופיעו.
יכול להיות שלא תופיע הודעת שגיאה בממשק המשתמש של Chat, אבל יש הודעות שגיאה תיאוריות ונתוני יומן זמינים כדי לעזור לכם לתקן שגיאות כשמופעלת רישום שגיאות ביומן של אפליקציות ל-Chat. כדי לקבל עזרה בצפייה: לניפוי באגים ולתיקון שגיאות: פתרון בעיות ותיקון שגיאות ב-Google Chat
נושאים קשורים
- איך מעצבים הודעות?
- איך מקבלים פרטים על הודעות?
- הצגת רשימה של ההודעות במרחבים משותפים
- איך מעדכנים את ההודעה?
- איך מוחקים הודעות?
- זיהוי משתמשים בהודעות של Google Chat.
- שליחת הודעות ל-Google Chat באמצעות webhooks נכנסים