הרשמה לאירועים של 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 שמאשרים את המינוי חייבים להיות חברים במרחב המשותף דרך חשבון Google או חשבון Google Workspace שלהם. תמיכה:
כל המרחבים של משתמש מסוים

//chat.googleapis.com/spaces/-

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

//cloudidentity.googleapis.com/users/USER

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

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

לקוח

//admin.googleapis.com/customers/CUSTOMER

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

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

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

תלוי בסוג האירוע (לדוגמה, space, space.message, space.membership או spaceReadState).

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

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

לדוגמה, אם משתמש מוסיף 20 משתמשים למרחב משותף בו-זמנית, יכול להיות שהאפליקציה ל-Chat תקבל אירוע באצ' (google.workspace.chat.membership.v1.batchCreated). המטען הייעודי (payload) של האירוע מכיל רשימה של כל המשאבים החדשים מסוג 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

נתוני אירוע

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

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

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

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

בטבלה הבאה מוצגות דוגמאות למטעני JSON ייעודיים למינוי למרחב המשותף spaces/AAAABBBBBB ב-Chat. לכל אירוע שהמינוי מקבל, המטען הייעודי (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"
  }
}
      
משתמש הופך לזמין ב-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",
    }
}
      
משתמש מגדיר את הזמינות שלו ב-Chat למצב Away. google.workspace.chat.availability.v1.updated

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

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

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

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
      
משתמש מגדיר את הזמינות שלו ב-Chat למצב Do not disturb. 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",
    }
}
      

מגבלות והתנהגויות של הצגת מודעות

מגבלות כלליות

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

מינויים של משתמשים

  • במינויים למשתמשים, אירועים שקשורים למשתמשים חדשים בצ'אטים אישיים או בצ'אטים קבוצתיים ללא שם (google.workspace.chat.membership.v1.created) מופעלים רק אחרי שההודעה הראשונה נשלחת.

מינויים של לקוחות

אלה המגבלות שחלות על מינויים של לקוחות:

  • לארגון ב-Google Workspace צריך להיות לפחות רישיון אחד למק"ט של Enterprise.
  • אפליקציית Chat יכולה ליצור רק מינוי אחד של לקוח לארגון נתון ב-Google Workspace. בארגון ב-Google Workspace יכולים להיות עד חמישה מינויים של לקוחות בסך הכול (שנוצרו על ידי אפליקציות שונות ל-Chat).

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

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

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

מרחבים שמנוהלים על ידי הארגון שלכם ב-Google Workspace

אם מתרחש שינוי במינוי במרחב שמנוהל על ידי הארגון ב-Google Workspace, הוא מועבר כאירוע במרחב.

הפורמט של שם המשאב של אירוע במרחב משותף הוא:

spaces/{spaceId}/spaceEvents/{spaceEventId}

מרחבים שמנוהלים על ידי ארגונים חיצוניים

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

הפורמט של שם המשאב של אירוע משתמש הוא:

users/{userId}/userEvents/{userEventId}