Send a message‪

במדריך הזה מוסברות הדרכים השונות שבהן אפליקציות Google Chat יכולות לשלוח הודעות:

  • לשלוח הודעות טקסט וכרטיסים בזמן אמת על ידי שליחת תגובות לאינטראקציה של משתמשים.
  • שולחים הודעות טקסט וכרטיסים באופן אסינכרוני על ידי קריאה לשיטה create במשאב Message.
  • להתחיל שרשור הודעות או לענות לו.
  • שליחת הודעה ומתן שם להודעה.

המשאב Message מייצג הודעות טקסט או כרטיס ב-Google Chat. אפשר create, get, update או delete הודעה ב-Google Chat API באמצעות קריאה לשיטות מתאימות. למידע נוסף על הודעות טקסט בכרטיסים, תוכלו לקרוא את הסקירה הכללית על הודעות ב-Google Chat.

במקום להפעיל את השיטה create במשאב Message של Google Chat API כדי לשלוח הודעות טקסט או כרטיס באופן אסינכרוני, אפליקציות Google Chat יכולות גם ליצור הודעות על מנת להגיב לאינטראקציות של משתמשים בזמן אמת. התגובות לאינטראקציות של המשתמשים לא מחייבות אימות ותומכות בסוגים אחרים של הודעות, כולל תיבות דו-שיח אינטראקטיביות ותצוגות מקדימות של קישורים. תוכלו לקרוא מידע נוסף במאמר איך לקבל אינטראקציות עם אפליקציית Google Chat ולהגיב עליהן.

דרישות מוקדמות

Node.js

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. אין צורך בהגדרות אישיות כדי לשלוח הודעות בזמן אמת.

Apps Script

שליחת הודעות טקסט

בקטע הזה מוסבר איך לשלוח הודעות טקסט בשתי הדרכים הבאות:

  • לשלוח הודעת טקסט בזמן אמת באמצעות תגובה לאינטראקציה של משתמש.
  • שולחים הודעת טקסט באמצעות קריאה אסינכרונית ל-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

  1. בספריית העבודה, יוצרים קובץ בשם chat_create_text_message_app.py.
  2. יש לכלול את הקוד הבא ב-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)
    
  3. בקוד, מחליפים את SPACE בשם של מרחב משותף, שאותו אפשר לקבל מה-method spaces.list() ב-Chat API או מכתובת ה-URL של המרחב המשותף.

  4. בספריית העבודה, יוצרים ומריצים את הדוגמה:

    python3 chat_create_text_message_app.py
    

ה-Chat API מחזיר מופע של Message שכולל פרטים על ההודעה שנשלחת.

שליחת הודעת טקסט עם אימות משתמש

כך שולחים הודעת טקסט באמצעות אימות משתמש:

Python

  1. בספריית העבודה, יוצרים קובץ בשם chat_create_text_message_user.py.
  2. יש לכלול את הקוד הבא ב-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 membership.
        print(result)
    
    if __name__ == '__main__':
        main()
    
  3. בקוד, מחליפים את SPACE בשם של מרחב משותף, שאותו אפשר לקבל מה-method spaces.list() ב-Chat API או מכתובת ה-URL של המרחב המשותף.

  4. בספריית העבודה, יוצרים ומריצים את הדוגמה:

    python3 chat_create_text_message_user.py
    

ה-Chat API מחזיר מופע של Message שכולל פרטים על ההודעה שנשלחת.

שליחת הודעות בכרטיס

בקטע הזה מוסבר איך לשלוח הודעות בכרטיס בשתי הדרכים הבאות:

  • לשלוח הודעה לגבי כרטיס בזמן אמת באמצעות תגובה לאינטראקציה של משתמש.
  • כדי לשלוח הודעות בכרטיס, מבצעים קריאה אסינכרונית ל-Google Chat API.


עצב כרטיסים והצג תצוגה מקדימה שלהם באמצעות הכלי ליצירת כרטיסים.

לפתיחת הכלי ליצירת כרטיסים

שליחה של הודעת כרטיס בזמן אמת

אפליקציות Chat יכולות ליצור הודעות בכרטיס בתגובה לאינטראקציה של משתמש, למשל כאשר משתמש שולח הודעה לאפליקציית Chat או מוסיף את אפליקציית Chat למרחב משותף. מידע נוסף על שליחת תגובות לאינטראקציות של משתמשים זמין במאמר קבלת אירועי אינטראקציה באפליקציות של Chat ותגובה אליהם.

בדוגמה הזו, משתמש שולח הודעה לאפליקציית Chat, ואפליקציית Chat שולחת הודעת כרטיס עם שם המשתמש ותמונת הדמות שלו:

אפליקציית Chat שמגיבה עם כרטיס עם השם המוצג ותמונת הדמות של השולח.

Node.js

result/avatar-app/index.js (צומת/avatar-app/index.js)
/**
 * Google Cloud Function that responds to messages sent from a
 * Google Chat room.
 *
 * @param {Object} req Request sent from Google Chat room
 * @param {Object} res Response to send back
 */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Google Chat ' +
      'Room.');
  }

  const sender = req.body.message.sender.displayName;
  const image = req.body.message.sender.avatarUrl;

  const data = createMessage(sender, image);

  res.send(data);
};

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} imageUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, imageUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`,
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '},
  };

  const avatarImageWidget = {
    image: {imageUrl},
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Python

python/avatar-app/main.py
from typing import Any, Mapping

import flask
import functions_framework


# Google Cloud Function that responds to messages sent in
# Google Chat.
#
# @param {Object} req Request sent from Google Chat.
# @param {Object} res Response to send back.
@functions_framework.http
def hello_chat(req: flask.Request) -> Mapping[str, Any]:
  if req.method == "GET":
    return "Hello! This function must be called from Google Chat."

  request_json = req.get_json(silent=True)

  display_name = request_json["message"]["sender"]["displayName"]
  avatar = request_json["message"]["sender"]["avatarUrl"]

  response = create_message(name=display_name, image_url=avatar)

  return response


# Creates a card with two widgets.
# @param {string} name the sender's display name.
# @param {string} image_url the URL for the sender's avatar.
# @return {Object} a card with the user's avatar.
def create_message(name: str, image_url: str) -> Mapping[str, Any]:
  avatar_image_widget = {"image": {"imageUrl": image_url}}
  avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
  avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}

  header = {"title": f"Hello {name}!"}

  cards = {
      "text": "Here's your avatar",
      "cardsV2": [
          {
              "cardId": "avatarCard",
              "card": {
                  "name": "Avatar Card",
                  "header": header,
                  "sections": [avatar_section],
              },
          }
      ]
  }

  return cards

Apps Script

apps-script/avatar-app/hello-chat.gs
/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  const displayName = event.message.sender.displayName;
  const avatarUrl = event.message.sender.avatarUrl;

  return createMessage(displayName, avatarUrl);
}

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} avatarUrl the URL for the sender's avatar
 * @return {Object} a card with the sender's avatar.
 */
function createMessage(displayName, avatarUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '}
  };

  const avatarImageWidget = {
    image: {imageUrl: avatarUrl}
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget
    ],
  };

  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

שליחה של הודעת כרטיס באופן אסינכרוני

כדי לשלוח הודעה בכרטיס, צריך להעביר בבקשה את הפרטים הבאים:

  • באימות אפליקציות, מציינים את היקף ההרשאה של chat.bot. אי אפשר לשלוח הודעות בכרטיס עם אימות משתמשים.
  • קוראים ל-method create במשאב Message.

זוהי דוגמה להודעת כרטיס:

הודעת כרטיס שנשלחה באמצעות Chat API.

כך שולחים הודעת כרטיס עם אימות אפליקציות:

Python

  1. בספריית העבודה, יוצרים קובץ בשם chat_create_card_message.py.
  2. יש לכלול את הקוד הבא ב-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)
    
  3. בקוד, מחליפים את SPACE בשם של מרחב משותף, שאותו אפשר לקבל מה-method spaces.list ב-Chat API או מכתובת ה-URL של המרחב המשותף.

  4. בספריית העבודה, יוצרים ומריצים את הדוגמה:

    python3 chat_create_card_message.py
    

התחלת שרשור הודעות או מענה עליו

כדי להתחיל שרשור הודעות, צריך לשלוח הודעה ולהשאיר את השדה thread.name ריק. Google Chat מאכלס אותו כשיוצרים את השרשור. אם רוצים להתאים אישית את שם השרשור, אפשר לציין את השדה thread.threadKey.

כדי לענות לשרשור הודעות, צריך לשלוח הודעה שמציינת את השדה threadKey או name של השרשור. אם השרשור נוצר על ידי משתמש אחר או אפליקציית Chat אחרת, צריך להשתמש בשדה thread.name.

אם לא נמצא שרשור תואם, תוכלו לציין אם ההודעה צריכה להתחיל שרשור חדש או לא לפרסם, על ידי הגדרת השדה messageReplyOption.

כך מתחילים שרשור או משיבים לשרשור עם השדה threadKey שמוגדר כ-nameOfThread:

Python

  1. בספריית העבודה, יוצרים קובץ בשם chat_create_message_thread.py.
  2. יש לכלול את הקוד הבא ב-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)
    
  3. בקוד, מחליפים את SPACE בשם של מרחב משותף, שאותו אפשר לקבל מה-method spaces.list ב-Chat API או מכתובת ה-URL של המרחב המשותף.

  4. בספריית העבודה, יוצרים ומריצים את הדוגמה:

    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

  1. בספריית העבודה, יוצרים קובץ בשם chat_create_named_message.py.
  2. יש לכלול את הקוד הבא ב-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)
    
  3. בקוד, מחליפים את מה שכתוב בשדות הבאים:

    • SPACE: המזהה של המרחב המשותף שבו רוצים לפרסם את ההודעה. אפשר לקבל אותו מה-method spaces.list ב-Chat API או מכתובת ה-URL של המרחב המשותף.
    • NAME: השם המותאם אישית של ההודעה.
  4. בספריית העבודה, יוצרים ומריצים את הדוגמה:

    python3 chat_create_named_message.py
    

ה-Chat API מחזיר מופע של Message.

שליחת הודעות באופן פרטי

אפליקציות צ'אט יכולות לשלוח הודעות טקסט בכרטיס באופן פרטי, כך שרק משתמש אחד במרחב המשותף יהיה גלוי. כדי לשלוח הודעה באופן פרטי, צריך לציין את השדה privateMessageViewer בהודעה. רק אפליקציות צ'אט יכולות לשלוח הודעות פרטיות. כדי לשלוח הודעה פרטית באופן אסינכרוני, צריך להשתמש באימות אפליקציות.

למידע נוסף, ראו שליחת הודעות פרטיות למשתמשי Google Chat.

פתרון בעיות

כשמוצגת הודעת שגיאה באפליקציה או בכרטיס של Google Chat, מוצגת בממשק של Chat ההודעה "משהו השתבש" או "לא ניתן לעבד את הבקשה שלך". לפעמים לא מוצגת הודעת שגיאה בממשק המשתמש של Chat, אבל קיבלתי תוצאה לא צפויה באפליקציה או בכרטיס של Chat. למשל, יכול להיות שלא תופיע הודעה על כרטיס.

יכול להיות שהודעת השגיאה לא תוצג בממשק המשתמש של Chat, אבל יש הודעות שגיאה תיאוריות ונתוני יומן שיכולים לעזור לכם לתקן שגיאות כשמפעילים רישום שגיאות באפליקציות של Chat. לקבלת עזרה בהצגה, בניפוי באגים ובתיקון שגיאות, אפשר להיעזר במאמר פתרון בעיות ותיקון שגיאות ב-Google Chat.