הרשמה לאירועים של Google Chat

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

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

אירועים נתמכים ב-Chat

מינויים ל-Google Workspace מאפשרים לקבל אירועים לגבי סוגי השינויים הבאים ב-Chat:

  • הודעות חדשות, מעודכנות או שנמחקו במרחב.
  • תגובות חדשות או תגובות שהוסרו להודעה.
  • חברים חדשים, מעודכנים או שהוסרו מהמרחב.
  • שינויים במרחב שאליו נרשמתם, כמו שם או תיאור מעודכנים של המרחב.

משאבים שאפשר לעקוב אחרי אירועים שקורים בהם

כדי לקבל אירועים, צריך לציין משאב של Chat למעקב, שנקרא משאב היעד של המינוי.

‫Google Workspace Events API תומך במשאבי היעד הבאים של Chat:

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

//chat.googleapis.com/spaces/SPACE

כאשר SPACE הוא המזהה ב שם המשאב של משאב space ב-Chat API. אפשר לאתר את המזהה בכתובת ה-URL של המרחב או באמצעות ה-method‏ spaces.list().

 המשתמש ב-Chat או אפליקציית Chat שמאשרים את המינוי צריכים להיות חברים במרחב דרך חשבון Google Workspace או חשבון Google. תמיכה:
כל המרחבים של משתמש

//chat.googleapis.com/spaces/-

 המינוי מקבל רק אירועים של מרחבים שהמשתמש הוא חבר בהם דרך חשבון Google Workspace או חשבון Google. תומך רק באימות משתמשים.
משתמש

//cloudidentity.googleapis.com/users/USER

כאשר USER הוא המזהה ב שם המשאב של משאב user ב-Chat API. פרטים נוספים זמינים במאמר בנושא זיהוי משתמשי Google Chat וציון שלהם.

המנוי מקבל רק אירועים שקשורים למשתמש שאישר את המנוי. משתמש לא יכול לאשר מינוי בשם משתמשים אחרים. תומך רק באימות משתמש.

סוגי אירועים ליצירת מינויים

כשיוצרים מינוי, משתמשים בשדה eventTypes[] כדי לציין אילו סוגי אירועים רוצים לקבל. סוגי האירועים מעוצבים לפי מפרט CloudEvents, כמו google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.

לדוגמה, כדי לקבל אירועים לגבי משתמשים שמצטרפים למרחב ב-Chat, צריך לציין את המרחב כמשאב היעד ואת סוג האירוע כ-google.workspace.chat.membership.v1.created. כדי לקבל אירועים לגבי משתמש מסוים שמצטרף למרחב כלשהו, צריך לציין את המשתמש כמשאב היעד ואת סוג האירוע כ-google.workspace.chat.membership.v1.created. מידע נוסף על אופן הפעולה של אירועים זמין במאמר מבנה האירועים ב-Google Workspace.

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

סוג האירוע אופן הלימוד נתוני משאבים
מינויים למרחבים  
הודעה מתפרסמת.

google.workspace.chat.message.v1.created

space.message
הודעה מתעדכנת.

google.workspace.chat.message.v1.updated

space.message
הודעה נמחקת.

google.workspace.chat.message.v1.deleted

space.message
נוצרת תגובה.

google.workspace.chat.reaction.v1.created

space.message.reaction
תגובה באמוג'י נמחקת.

google.workspace.chat.reaction.v1.deleted

space.message.reaction
המשתמש יצורף למרחב.

google.workspace.chat.membership.v1.created

space.membership
הפרטים של משתתף במרחב עודכנו.

google.workspace.chat.membership.v1.updated

space.membership
משתמש הוסר מהמרחב.

google.workspace.chat.membership.v1.deleted

space.membership
המרחב יעודכן.

google.workspace.chat.space.v1.updated

space
המרחב נמחק.

google.workspace.chat.space.v1.deleted

space
מינויים למשתמשים  
המשתמש מצטרף למרחב.

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

google.workspace.chat.membership.v1.created

space.membership
המינוי של המשתמש למרחב עודכן.

google.workspace.chat.membership.v1.updated

space.membership
המשתמש יוסר כחבר ישיר במרחב.

google.workspace.chat.membership.v1.deleted

space.membership
סטטוס הקריאה של המשתמש במרחב עודכן. ( תצוגה מקדימה למפתחים)

google.workspace.chat.spaceReadState.v1.updated

spaceReadState
סטטוס הקריאה של השרשור של המשתמש עודכן. ( תצוגה מקדימה למפתחים)

google.workspace.chat.threadReadState.v1.updated

threadReadState

סוגי אירועים באצווה (פלט בלבד)

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

לדוגמה, אם משתמש מוסיף 20 משתמשים למרחב בו-זמנית, יכול להיות שאפליקציית Chat תקבל אירוע של קבוצת משתמשים (google.workspace.chat.membership.v1.batchCreated). מטען הנתונים של האירוע מכיל רשימה של כל משאבי Membership המשתמשים החדשים שנוצרו כשהמשתמש הוסיף את החברים למרחב.

מקבלים אירוע אצווה לכל סוג אירוע שנרשמים אליו, כך שלא צריך לציין אירועי אצווה כשיוצרים מינוי. לדוגמה, אם נרשמתם למינוי של תגובות חדשות (google.workspace.chat.reaction.v1.created), אפליקציית Chat מוגדרת באופן אוטומטי לקבל אירועי תגובה בקבוצות (google.workspace.chat.reaction.v1.batchCreated).

בטבלה הבאה מוצגים אירועים אפשריים של קבוצות למינוי:

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

google.workspace.chat.message.v1.batchCreated
כמה הודעות מתעדכנות.

google.workspace.chat.message.v1.batchUpdated
כמה הודעות נמחקות.

google.workspace.chat.message.v1.batchDeleted
נוצרות כמה תגובות באמוג'י.

google.workspace.chat.reaction.v1.batchCreated
נמחקו כמה תגובות באמוג'י.

google.workspace.chat.reaction.v1.batchDeleted
כמה משתתפים נוספו למרחב המשותף שהמשתמש רשום אליו, או שהמשתמש נוסף לכמה מרחבים.

google.workspace.chat.membership.v1.batchCreated
כמה חברים עודכנו במרחב שהמשתמש רשום אליו או עבור המשתמש הרשום.

google.workspace.chat.membership.v1.batchUpdated
מספר אנשים הוסרו מהמרחב המשותף שהמשתמש רשום אליו, או שהמשתמש הוסר מכמה מרחבים.

google.workspace.chat.membership.v1.batchDeleted
במרחב יש כמה עדכונים.

google.workspace.chat.space.v1.batchUpdated
מתעדכנים כמה סטטוסים של קריאה במרחבים עבור המשתמש הרשום. ( תצוגה מקדימה למפתחים)

google.workspace.chat.spaceReadState.v1.batchUpdated
מצב הקריאה של כמה שרשורים מתעדכן עבור המשתמש הרשום. ( תצוגה מקדימה למפתחים)

google.workspace.chat.threadReadState.v1.batchUpdated

נתוני אירוע

בקטע הזה מתוארים נתוני אירועים ומטענים לדוגמה של אירועים ב-Chat.

כשמתקבל אירוע מ-Chat במינוי ל-Google Workspace, השדה data מכיל את מטען הייעודי (payload) של האירוע. מטען הנתונים הזה מכיל מידע על משאב Google Workspace שהשתנה. לדוגמה, אם נרשמתם לאירועים של חברות במרחב, מטען הייעודי (payload) של האירועים האלה מכיל מידע על משאב spaces.membership שעבר שינוי.

נתוני משאבים במטען הייעודי (payload) של האירוע

כשיוצרים מינוי, אפשר לציין אם רוצים שהמטען הייעודי (Payload) יכלול פרטים על המשאב, או רק את השם של המשאב. לדוגמה, אם רוצים לקבל אירועים לגבי חברים במרחב ב-Chat, צריך לציין אילו שדות של משאב החברות רוצים לקבל במטען הייעודי (payload) של האירוע.

בטבלה הבאה מופיעות דוגמאות למטענים ייעודיים (payloads) של JSON להרשמה למינוי של מרחב ב-Chat‏ spaces/AAAABBBBBB. לכל אירוע שהמינוי מקבל, המטען הייעודי (payload) מופיע בשדה data של האירוע:

דוגמה סוג האירוע מטען ייעודי (payload) של JSON

משתמש מפרסם הודעה במרחב עם הכיתוב "Hello world".

google.workspace.chat.message.v1.created

כולל נתונים של משאבים:

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID",
        "sender":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "2023-09-07T21:37:36.260127Z",
        "text": "Hello world",
        "thread":
        {
            "name": "spaces/SPACE_ID/threads/THREAD_ID"
        },
        "space":
        {
            "name": "spaces/SPACE_ID"
        },
        "argumentText": "Hello world"
    }
}

לא כולל נתוני משאבים:

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID"
    }
}
משתמש הופך למנהל של המרחב.

google.workspace.chat.membership.v1.updated

כולל נתונים של משאבים:

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID",
        "state": "JOINED",
        "member":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "1970-01-01T00:00:00Z",
        "role": "ROLE_MANAGER"
    }
}

לא כולל נתוני משאבים:

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID"
    }
}
משתמש מעדכן את התיאור של המרחב ל'צוות המכירות של Cymbal Labs'. google.workspace.chat.space.v1.updated

כולל נתונים של משאבים:

{
    "space":
    {
        "name": "spaces/SPACE_ID",
        "displayName": "Cymbal Sales",
        "spaceThreadingState": "THREADED_MESSAGES",
        "spaceType": "SPACE",
        "spaceDetails":
        {
            "description": "Sales team for Cymbal Labs."
        },
        "spaceHistoryState": "HISTORY_ON"
    }
}

לא כולל נתוני משאבים:

{
    "space":
    {
        "name": "spaces/SPACE_ID"
    }
}
שני משתמשים ב-Chat נוספו למרחב באותו זמן. google.workspace.chat.membership.v1.batchCreated

כולל נתונים של משאבים:

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        }
    ]
}

לא כולל נתוני משאבים:

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        }
    ]
}
משתמש מגיב להודעה באמוג'י 😊. google.workspace.chat.reaction.v1.created

כולל נתוני משאבים:

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        "user":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}

לא כולל נתוני משאבים:

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
    }
}
המשתמשים מגיבים להודעה עם האמוג'י 😊 והאמוג'י 😸. google.workspace.chat.reaction.v1.batchCreated

כולל נתוני משאבים:

{
    "reactions": [
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😊"
            }
          }
        },
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😸"
            }
          }
        }
    ]
}

לא כולל נתוני משאבים:

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
        },
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        }
      }
    ]
}
משתמש נכנס למרחב שלא נקרא, והסטטוס של הקריאה במרחב מתעדכן. ( תצוגה מקדימה למפתחים) google.workspace.chat.spaceReadState.v1.updated

כולל נתוני משאבים:

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState",
    "lastReadTime": "2026-04-14T14:03:46.431760Z"
  }
}

לא כולל נתוני משאבים:

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState"
  }
}
משתמש קורא הודעה בשרשור, והסטטוס של השרשור משתנה ל'נקרא'. ( תצוגה מקדימה למפתחים) google.workspace.chat.threadReadState.v1.updated

כולל נתוני משאבים:

{
  "threadReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/threads/THREAD_ID/threadReadState",
    "lastReadTime": "2026-04-14T14:03:46.431760Z"
  }
}

לא כולל נתוני משאבים:

{
  "threadReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/threads/THREAD_ID/threadReadState"
  }
}

מגבלות
  • במינויים למשתמשים, אירועים לגבי חברים חדשים בצ'אטים ישירים או בצ'אטים קבוצתיים ללא שם (google.workspace.chat.membership.v1.created), מופעלים רק אחרי פרסום ההודעה הראשונה.
  • כדי לקבל אירועים שקשורים לחברות במרחב, המשתמש או אפליקציית Chat צריכים להיות חברים ישירים במרחב. אם הם נוספו, עודכנו או הוסרו בעקיפין מהמרחב דרך קבוצה ב-Google, המינוי לא יקבל את אירועי החברות האלה. כדי להבין איך עובד החברות בקבוצות Google, אפשר לקרוא את המאמר בנושא צירוף קבוצות מ'קבוצות Google' למרחבים משותפים.