Đă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 Chat mà ứng dụng Chat có thể đăng ký bằng API Sự kiện 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 Google Chat API. Khi gọi Chat API, bạn có thể truy xuất các sự kiện theo định kỳ hoặc nắm bắ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ề những cách bạn có thể nhận và phản hồi các sự kiện trên Chat, hãy xem phần Làm việc với các sự kiện trên Chat trong tài liệu về Chat.

Các sự kiện được hỗ trợ trên Chat

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

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

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

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

Google Workspace Events API hỗ trợ các tài nguyên đích sau đây cho Chat:

Tài nguyên mục tiêu Định dạng Giới hạn
Không gian

//chat.googleapis.com/spaces/SPACE

trong đó SPACE là mã nhận dạng trong tên tài nguyên của tài nguyên Chat API space. Bạn có thể lấy mã nhận dạng từ URL của không gian hoặc bằng cách sử dụng phương thức spaces.list().

 Người dùng Chat hoặc ứng dụng Chat uỷ quyền đăng ký phải là thành viên của không gian thông qua Tài khoản Google hoặc Tài khoản Google Workspace của họ. Hỗ trợ:
Tất cả không gian của một người dùng

//chat.googleapis.com/spaces/-

 Dịch vụ đăng ký chỉ nhận các sự kiện cho những không gian mà người dùng là thành viên thông qua tài khoản Google Workspace hoặc Tài khoản Google của họ. Chỉ hỗ trợ xác thực người dùng.
Người dùng

//cloudidentity.googleapis.com/users/USER

trong đó USER là mã nhận dạng trong tên tài nguyên của tài nguyên Chat API user. Để biết thông tin chi tiết, hãy xem bài viết Xác định và chỉ định người dùng Google Chat.

Chỉ những sự kiện về người dùng đã uỷ quyền cho gói thuê bao mới được gửi đến gói thuê bao. Người dùng không thể uỷ quyền đăng ký thay cho người dùng khác. Chỉ hỗ trợ xác thực người dùng.

Các loại sự kiện để tạo gói thuê bao

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

Ví dụ: để nhận sự kiện về người dùng tham gia một không gian Chat, 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 vào bất kỳ không gian nào, 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 các sự kiện, hãy xem phần Cấu trúc của các 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 việc đăng ký theo dõi không gian và đăng ký theo dõi người dùng. Để tìm hiểu về các trường hợp ngoại lệ đối với những yếu tố kích hoạt sự kiện, hãy xem phần Hạn chế.

Loại sự kiện Định dạng Dữ liệu tài nguyên
Đăng ký theo dõi không gian  
Một thông báo được đăng.

google.workspace.chat.message.v1.created

space.message
Một thông báo được cập nhật.

google.workspace.chat.message.v1.updated

space.message
Một tin nhắn bị xoá.

google.workspace.chat.message.v1.deleted

space.message
Một biểu cảm phản ứng được tạo.

google.workspace.chat.reaction.v1.created

space.message.reaction
Một lượt thể hiện cảm xúc bị xoá.

google.workspace.chat.reaction.v1.deleted

space.message.reaction
Một thành viên được thêm vào không gian.

google.workspace.chat.membership.v1.created

space.membership
Một thành viên được cập nhật trong không gian.

google.workspace.chat.membership.v1.updated

space.membership
Một thành viên bị loại khỏi không gian.

google.workspace.chat.membership.v1.deleted

space.membership
Không gian được cập nhật.

google.workspace.chat.space.v1.updated

space
Không gian này sẽ bị xoá.

google.workspace.chat.space.v1.deleted

space
Gửi thông báo đăng ký cho người dùng  
Người dùng trở thành thành viên của một không gian.

Không phải thành viên mới nào cũng kích hoạt sự kiện. Để biết thông tin chi tiết, hãy xem phần Các điểm hạn chế

google.workspace.chat.membership.v1.created

space.membership
Hệ thống sẽ cập nhật trạng thái thành viên của người dùng trong một không gian.

google.workspace.chat.membership.v1.updated

space.membership
Người dùng đó sẽ bị xoá khỏi danh sách thành viên trực tiếp của một không gian.

google.workspace.chat.membership.v1.deleted

space.membership
Trạng thái đã đọc của người dùng trong không gian được cập nhật. ( Bản dùng trước cho nhà phát triển)

google.workspace.chat.spaceReadState.v1.updated

spaceReadState
Trạng thái đã đọc của luồng của người dùng sẽ được cập nhật. ( Bản dùng trước cho nhà phát triển)

google.workspace.chat.threadReadState.v1.updated

threadReadState

Các 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ủa bạn cũng có thể nhận được các sự kiện hàng loạt. Sự kiện hàng loạt là 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. Tải trọng của một sự kiện hàng loạt chứa danh sách tất cả các tài nguyên đã thay đổi.

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

Bạn sẽ nhận được một sự kiện hàng loạt cho mọi loại sự kiện mà bạn đăng ký, vì vậy bạn không cần chỉ định sự kiện hàng loạt khi tạo một lượt đăng ký. Ví dụ: nếu bạn đăng ký nhận phản ứng mới (google.workspace.chat.reaction.v1.created), ứ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 hàng loạt có thể xảy ra đối với một gói thuê bao:

Loại sự kiện theo lô Định dạng
Nhiều thông báo được đăng.

google.workspace.chat.message.v1.batchCreated
Nhiều thông báo được cập nhật.

google.workspace.chat.message.v1.batchUpdated
Nhiều tin nhắn bị xoá.

google.workspace.chat.message.v1.batchDeleted
Nhiều biểu tượng thể hiện cảm xúc được tạo.

google.workspace.chat.reaction.v1.batchCreated
Nhiều lượt thể hiện cảm xúc bị xoá.

google.workspace.chat.reaction.v1.batchDeleted
Nhiều thành viên được thêm vào không gian mà bạn đã đăng ký, hoặc người dùng mà bạn đã đăng ký được thêm vào nhiều không gian.

google.workspace.chat.membership.v1.batchCreated
Nhiều thành viên được cập nhật trong không gian đã đăng ký hoặc cho người dùng đã đăng ký.

google.workspace.chat.membership.v1.batchUpdated
Nhiều thành viên bị xoá khỏi không gian đã đăng ký hoặc người dùng đã đăng ký bị xoá khỏi nhiều không gian.

google.workspace.chat.membership.v1.batchDeleted
Không gian này có nhiều nội dung cập nhật.

google.workspace.chat.space.v1.batchUpdated
Nhiều trạng thái đã đọc trong không gian được cập nhật cho người dùng đã đăng ký. ( Bản dùng trước cho nhà phát triển)

google.workspace.chat.spaceReadState.v1.batchUpdated
Nhiều trạng thái đọc của luồng được cập nhật cho người dùng đã đăng ký. ( Bản dùng trước cho nhà phát triển)

google.workspace.chat.threadReadState.v1.batchUpdated

Dữ liệu sự kiện

Phần này mô tả dữ liệu sự kiện và các 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 đó. Tải trọng 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 thông báo về các sự kiện dành cho thành viên trong một không gian, thì tải trọng của 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 một 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 các sự kiện về thành viên trong một không gian trò chuyện, hãy chỉ định những trường nào 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 một lượt đăng ký phòng 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:

Ví dụ Loại sự kiện Tải trọng JSON

Một người dùng đăng tin nhắn "Xin chào thế giới" trong không gian.

google.workspace.chat.message.v1.created

Bao gồm dữ liệu tài nguyê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"
    }
}

Không bao gồm dữ liệu tài nguyên:

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID"
    }
}
Một người dùng trở thành người quản lý không gian.

google.workspace.chat.membership.v1.updated

Bao gồm dữ liệu tài nguyên:

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

Không bao gồm dữ liệu tài nguyên:

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID"
    }
}
Một người dùng cập nhật nội dung mô tả của không gian thành "Nhóm bán hàng của Cymbal Labs". google.workspace.chat.space.v1.updated

Bao gồm dữ liệu tài nguyên:

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

Không bao gồm dữ liệu tài nguyên:

{
    "space":
    {
        "name": "spaces/SPACE_ID"
    }
}
Hai người dùng Chat được thêm vào không gian cùng một lúc. google.workspace.chat.membership.v1.batchCreated

Bao gồm dữ liệu tài nguyên:

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

Không bao gồm dữ liệu tài nguyên:

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        }
    ]
}
Một người dùng thể hiện cảm xúc với tin nhắn bằng biểu tượng 😊. google.workspace.chat.reaction.v1.created

Bao gồm dữ liệu tài nguyên:

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

Không bao gồm dữ liệu tài nguyên:

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
    }
}
Người dùng thể hiện cảm xúc với một tin nhắn bằng biểu tượng 😊 và 😸. google.workspace.chat.reaction.v1.batchCreated

Bao gồm dữ liệu tài nguyên:

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

Không bao gồm dữ liệu tài nguyên:

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
        },
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        }
      }
    ]
}
Người dùng truy cập vào một không gian chưa đọc, thao tác này sẽ cập nhật trạng thái đã đọc của không gian đó. ( Bản dùng trước cho nhà phát triển) google.workspace.chat.spaceReadState.v1.updated

Bao gồm dữ liệu tài nguyên:

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

Không bao gồm dữ liệu tài nguyên:

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState"
  }
}
Người dùng đọc một tin nhắn trong chuỗi tin nhắn, việc này sẽ cập nhật trạng thái đã đọc của chuỗi tin nhắn. ( Bản dùng trước cho nhà phát triển) google.workspace.chat.threadReadState.v1.updated

Bao gồm dữ liệu tài nguyên:

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

Không bao gồm dữ liệu tài nguyên:

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

Các điểm hạn chế
  • Đối với việc đăng ký theo dõi 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.
  • Để nhận các sự kiện về tư cách 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ì dịch vụ đăng ký sẽ không nhận được những sự kiện thành viên đó. Để tìm hiểu cách hoạt động của thành viên trong nhóm trên Google Groups, hãy xem phần Thêm nhóm trên Google Groups vào không gian.