Đăng ký nhận thông báo về sự kiện trong Google Chat

Trang này mô tả các sự kiện trong Chat mà một ứng dụng Chat có thể đăng ký bằng API Sự kiện của Google Workspace. Sau khi quyết định loại sự kiện bạn cần, hãy tạo một gói thuê bao để bắt đầu nhận sự kiện từ Chat.

Ngoài việc đăng ký nhận sự kiện, bạn cũng có thể truy vấn sự kiện bằng cách gọi API Google Chat. Khi gọi Chat API, bạn có thể truy xuất các sự kiện theo định kỳ hoặc cập nhật các sự kiện mà bạn có thể đã bỏ lỡ trong một gói thuê bao do sự cố ngừng hoạt động. Để tìm hiểu về các cách bạn có thể nhận và phản hồi các sự kiện trong Chat, hãy xem phần Xử lý các sự kiện trong Chat trong tài liệu về Chat.

Sự kiện được hỗ trợ trong Chat

Gói thuê bao Google Workspace cho phép bạn nhận sự kiện về các loại thay đổi sau trong Chat:

• Tin nhắn mới, được cập nhật hoặc bị xoá trong không gian.
• Phản ứng mới hoặc đã bị xoá đối với một tin nhắn.
• Thành viên mới, được cập nhật hoặc bị xoá trong không gian.
• Những thay đổi đối với không gian mà bạn đã đăng ký, chẳng hạn như tên hoặc nội dung mô tả mới của không gian.
• Thay đổi đối với tình trạng rảnh/bận của người dùng.
• Thay đổi đối với spaceReadState hoặc threadReadState của người dùng.

Tài nguyên mà bạn có thể theo dõi để biết các sự kiện

Để nhận sự kiện, bạn cần chỉ định một tài nguyên Chat cần theo dõi, gọi là tài nguyên mục tiêu của gói thuê bao.

API Google Workspace Events hỗ trợ các tài nguyên mục tiêu sau đây cho Chat:

Loại sự kiện để tạo gói thuê bao

Khi bạn tạo một gói thuê bao, hãy sử dụng trường eventTypes[] để chỉ định loại sự kiện bạn muốn nhận. Các loại sự kiện được định dạng theo quy cách của CloudEvents, chẳng hạn như google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.

Ví dụ: để nhận sự kiện về việc người dùng tham gia một không gian trò chuyện, hãy chỉ định không gian đó làm tài nguyên mục tiêu và loại sự kiện là google.workspace.chat.membership.v1.created. Để nhận sự kiện về một người dùng nhất định tham gia không gian bất kỳ, hãy chỉ định người dùng đó làm tài nguyên mục tiêu và loại sự kiện là google.workspace.chat.membership.v1.created. Để tìm hiểu thêm về cách hoạt động của sự kiện, hãy xem bài viết Cấu trúc của sự kiện trên Google Workspace.

Bảng sau đây cho biết những loại sự kiện được hỗ trợ cho gói thuê bao đối với không gian và gói thuê bao đối với người dùng. Để tìm hiểu về các trường hợp ngoại lệ liên quan đến điều kiện kích hoạt sự kiện, hãy xem phần Giới hạn.

Loại sự kiện theo lô (chỉ có đầu ra)

Ngoài việc nhận các loại sự kiện mà bạn đăng ký, ứng dụng Chat cũng có thể nhận được các sự kiện theo lô. Sự kiện theo lô là một sự kiện đại diện cho nhiều sự kiện cùng loại xảy ra trong một khoảng thời gian ngắn. Trọng tải của một sự kiện theo lô chứa danh sách tất cả tài nguyên đã thay đổi.

Ví dụ: nếu một người dùng thêm 20 người dùng vào một không gian cùng một lúc, thì ứng dụng Chat của bạn có thể nhận được một sự kiện theo lô (google.workspace.chat.membership.v1.batchCreated). Trọng tải sự kiện chứa danh sách tất cả tài nguyên Membership mới được tạo khi người dùng thêm thành viên vào không gian.

Bạn sẽ nhận được sự kiện theo lô cho bất kỳ loại sự kiện nào mà bạn đăng ký, vì vậy, bạn không cần chỉ định sự kiện theo lô khi tạo gói thuê bao. Ví dụ: nếu bạn đăng ký nhận các phản ứng mới (google.workspace.chat.reaction.v1.created), thì ứng dụng Chat của bạn sẽ tự động được định cấu hình để nhận các sự kiện phản ứng theo lô (google.workspace.chat.reaction.v1.batchCreated).

Bảng sau đây cho thấy các sự kiện theo lô có thể xảy ra đối với một gói thuê bao:

Dữ liệu sự kiện

Phần này mô tả dữ liệu sự kiện và tải trọng mẫu cho các sự kiện trong Chat.

Khi gói thuê bao Google Workspace của bạn nhận được một sự kiện từ Chat, trường data sẽ chứa tải trọng cho sự kiện đó. Trọng tải này có thông tin về tài nguyên Google Workspace đã thay đổi. Ví dụ: nếu bạn đã đăng ký nhận sự kiện về thành viên trong một không gian, thì tải trọng cho các sự kiện này sẽ chứa thông tin về tài nguyên spaces.membership đã thay đổi.

Dữ liệu tài nguyên trong tải trọng sự kiện

Khi tạo gói thuê bao, bạn có thể chỉ định xem bạn muốn tải trọng bao gồm thông tin chi tiết về tài nguyên hay chỉ tên của tài nguyên. Ví dụ: nếu bạn muốn nhận sự kiện về thành viên trong một không gian Chat, hãy chỉ định những trường của tài nguyên thành viên mà bạn muốn nhận trong tải trọng sự kiện.

Bảng sau đây cung cấp ví dụ về tải trọng JSON cho gói thuê bao không gian Chat spaces/AAAABBBBBB. Đối với mỗi sự kiện mà gói thuê bao nhận được, tải trọng sẽ xuất hiện trong trường data của sự kiện:

{
    "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"
    }
}
      

{
    "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"
    }
}
      

{
    "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"
    }
}
      

{
    "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"
          }
        }
    ]
}
      

{
    "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"
    }
}
      

{
    "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",
        }
      }
    ]
}
      

{
  "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"
  }
}
      

{
  "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"
  }
}
      

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

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

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

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

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

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

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

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

{
    "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",
    }
}
      

Các hạn chế chung

• Để nhận sự kiện về thành viên, người dùng hoặc ứng dụng Chat phải là thành viên trực tiếp của không gian. Nếu họ được thêm, cập nhật hoặc xoá gián tiếp khỏi một không gian thông qua một nhóm trên Google Groups, thì gói thuê bao sẽ không nhận được các sự kiện về thành viên đó. Để tìm hiểu cách hoạt động của tư cách thành viên trong nhóm trên Google Groups, hãy xem bài viết Thêm một nhóm trên Google Groups vào một không gian.

Gói thuê bao của người dùng

• Đối với gói thuê bao cho người dùng, các sự kiện về thành viên mới trong tin nhắn trực tiếp hoặc cuộc trò chuyện nhóm chưa đặt tên (google.workspace.chat.membership.v1.created) chỉ kích hoạt sau khi tin nhắn đầu tiên được đăng.

Gói thuê bao của khách hàng

Đối với gói thuê bao của khách hàng, các giới hạn sau đây sẽ được áp dụng:

• Tổ chức Google Workspace phải có ít nhất một giấy phép SKU Enterprise.
• Một ứng dụng Chat chỉ có thể tạo một gói thuê bao khách hàng cho một tổ chức Google Workspace nhất định. Một tổ chức Google Workspace có thể có tổng cộng tối đa 5 gói thuê bao của khách hàng (do các ứng dụng Chat khác nhau tạo).

Đối với gói thuê bao của khách hàng, việc phân phối sự kiện tuân theo các quy tắc chung sau:

• Sự kiện trong không gian: Chỉ được gửi nếu sự kiện xảy ra trong một không gian do tổ chức Google Workspace của bạn quản lý.
• Sự kiện của người dùng: Chỉ được gửi nếu sự kiện xảy ra với một người dùng thuộc tổ chức Google Workspace của bạn.

Trường hợp ngoại lệ duy nhất đối với các quy tắc này là sự kiện dành cho hội viên. Gói thuê bao của bạn có thể nhận sự kiện về thành viên từ cả không gian do tổ chức của bạn quản lý và không gian do tổ chức bên ngoài quản lý, nhưng cách phân phối sự kiện phụ thuộc vào tổ chức quản lý không gian:

Không gian do tổ chức Google Workspace của bạn quản lý

Nếu có sự thay đổi về thành viên trong một không gian do tổ chức Google Workspace quản lý, thì sự thay đổi đó sẽ được phân phối dưới dạng sự kiện trong không gian.

Tên tài nguyên của một sự kiện trong không gian sử dụng định dạng sau:

spaces/{spaceId}/spaceEvents/{spaceEventId}

Không gian do các tổ chức bên ngoài quản lý

Nếu tư cách thành viên của một người dùng do tổ chức Google Workspace của bạn quản lý thay đổi trong một không gian do một tổ chức bên ngoài quản lý (ví dụ: một không gian có tên bên ngoài hoặc một tin nhắn trực tiếp do một người dùng bên ngoài tạo), thì gói thuê bao của bạn sẽ nhận được sự kiện này dưới dạng sự kiện của người dùng.

Tên tài nguyên của sự kiện người dùng sử dụng định dạng sau:

users/{userId}/userEvents/{userEventId}

Chủ đề có liên quan

• Cấu trúc của sự kiện trên Google Workspace
• Chọn phạm vi OAuth
• Tạo gói thuê bao để nhận sự kiện trong Chat