שליחת הודעות באמצעות Google Chat API

במדריך הזה מוסבר איך לקרוא ל-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.

קריאה ל-method messages.create() באמצעות אימות אפליקציה.
איור 1: כשמפעילים אימות אפליקציות, אפליקציית Chat שולחת את ההודעה. חשוב לדעת שהשולח הוא לא בן אדם ב-Chat, ליד השם שלו מופיע הכיתוב App.

כשאתם מבצעים אימות כמשתמשים, אפליקציית Chat שולחת את הודעה בשם המשתמש. Chat גם משייך את רוצה לשלוח את ההודעה לאפליקציית Chat באמצעות הצגת השם שלה?

קריאה ל-method messages.create() עם אימות משתמש.
איור 2: באימות המשתמש, המשתמש שולח את ההודעה וב-Chat השם של אפליקציית Chat ליד השם של המשתמש.

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

במדריך הזה מוסבר איך להשתמש בכל אחד מסוגי האימות כדי לשלוח הודעה באמצעות Chat API.

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

Python

  • Python 3.6 ומעלה
  • הכלי לניהול חבילות pip
  • ספריות הלקוח העדכניות של Google. כדי להתקין או לעדכן אותם, מריצים את הפקודה הבאה בממשק שורת הפקודה: 
    pip3 install --upgrade google-api-python-client google-auth-oauthlib

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

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

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

כדי להפעיל את messages.create() באמצעות אימות משתמש, צריך לציין את השדות הבאים בבקשה:

  • היקף ההרשאה שתומך באימות משתמשים בשיטה הזו. הדוגמה הבאה משתמשת ההיקף chat.messages.create.
  • המשאב Space שבו שרוצים לפרסם את ההודעה. המשתמש המאומת חייב להיות חבר המרחב המשותף.
  • Message של המשאבים שצריך ליצור. כדי להגדיר את תוכן ההודעה, עליך לכלול את text השדה הזה.

אפשר לכלול גם את הפרטים הבאים:

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

Python

  1. בספריית העבודה, יוצרים קובץ בשם chat_create_message_user.py

  2. צריך לכלול את הקוד הבא ב-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 של המרחב המשותף.

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

    python3 chat_create_message_user.py

  4. אם מופיעה כתובת URL, צריך לפתוח את כתובת ה-URL כדי לאשר את אפליקציית Chat בהתאם להיקף שהשתמשתם בו בקשה.

אפליקציית Chat יוצרת את ההודעה, משתמש מפרסם את ההודעה במרחב. בממשק שורת הפקודה, Chat API מחזיר את המופע של משאב Message.

שליחת הודעה בתור אפליקציית Chat

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

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

כדי להפעיל את messages.create() באמצעות אימות אפליקציות, צריך לציין השדות הבאים בבקשה:

  • chat.bot היקף ההרשאה.
  • המשאב Space שבו שרוצים לפרסם את ההודעה. אפליקציית Chat צריכה להיות משתמש במרחב המשותף.
  • Message של המשאבים שצריך ליצור. כדי להגדיר את תוכן ההודעה, אפשר לכלול טקסט עשיר (text), ממשק כרטיס אחד או יותר (cardsV2), או לשניהם.

אפשר לכלול גם את הפרטים הבאים:

הגודל המקסימלי של הודעה (כולל טקסט או כרטיסים) הוא 32,000 בייטים. כדי לשלוח הודעה גדולה יותר מהגודל הזה, צריך להשתמש באפליקציית Chat צריך לשלוח מספר הודעות.

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

Python

  1. בספריית העבודה, יוצרים קובץ בשם chat_create_message_app.py

  2. צריך לכלול את הקוד הבא ב-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 של המרחב המשותף.

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

    python3 chat_create_message_app.py

אפליקציית Chat יוצרת ומפרסמת את ההודעה המרחב המשותף. בממשק שורת הפקודה, ה-Chat API מחזיר של המכונה החדשה משאב Message.

הוספת ווידג'טים אינטראקטיביים בתחתית הודעה

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

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

כדי להוסיף ווידג'טים של אביזרים, צריך לכלול את accessoryWidgets[] בשדה בגוף הבקשה ולציין ווידג'ט אחד או יותר שרוצים לכלול.

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

ווידג&#39;ט האביזר.
איור 5: הודעה באפליקציית Chat עם ווידג'טים של טקסט ואביזרים.

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