הרשמה לאירועים של 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
סטטוס הקריאה של המשתמש במרחב עודכן. ( גרסת Developer Preview)

google.workspace.chat.spaceReadState.v1.updated

spaceReadState
סטטוס הקריאה של השרשור של המשתמש עודכן. ( גרסת Developer Preview)

google.workspace.chat.threadReadState.v1.updated

threadReadState
הזמינות של המשתמש עודכנה.

google.workspace.chat.availability.v1.updated

user.availability

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

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

google.workspace.chat.spaceReadState.v1.batchUpdated
מתעדכנים כמה סטטוסים של קריאת שרשורים אצל המשתמש הרשום. ( גרסת Developer Preview)

google.workspace.chat.threadReadState.v1.batchUpdated

נתוני אירוע

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

כשמתקבל אירוע מ-Chat במינוי ל-Google Workspace, השדה data מכיל את מטען הייעודי (payload) של האירוע. מטען הייעודי (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",
        }
      }
    ]
}
משתמש נכנס למרחב שלא נקרא, והסטטוס של הקריאה במרחב מתעדכן. ( גרסת Developer Preview) 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"
  }
}
משתמש קורא הודעה בשרשור, והסטטוס של השרשור משתנה ל'נקרא'. ( גרסת Developer Preview) 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"
  }
}
משתמש הופך לזמין ב-Chat. google.workspace.chat.availability.v1.updated

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

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "ACTIVE"
    }
}

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

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
משתמש לא פעיל ב-Chat. google.workspace.chat.availability.v1.updated

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

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "IDLE",
    }
}

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

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
משתמש מגדיר את סטטוס הזמינות שלו לAway ב-Chat. google.workspace.chat.availability.v1.updated

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

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "AWAY",
    }
}

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

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
משתמש מגדיר את סטטוס הזמינות שלו לDo not disturb ב-Chat. google.workspace.chat.availability.v1.updated

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

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "DO_NOT_DISTURB",
        "doNotDisturbMetadata": {
          "expirationTime": "2026-03-24T18:36:31.337Z"
        }
    }
}

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

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
משתמש מגדיר סטטוס מותאם אישית ב-Chat. google.workspace.chat.availability.v1.updated

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

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "ACTIVE",
        "customStatus": {
          "text": "Be right back",
          "emoji": {
            "unicode": "👟"
          },
          "expireTime": "2026-03-24T18:38:05.583655Z"
        }
    }
}

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

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}

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