Google Chat 이벤트 구독하기

이 페이지에서는 Chat 앱이 Google Workspace Events API를 사용하여 구독할 수 있는 Chat 이벤트에 대해 설명합니다. 필요한 이벤트 유형을 결정한 후 구독을 만들어 Chat에서 이벤트를 수신합니다.

이벤트를 구독하는 것 외에도 Google Chat API를 호출하여 이벤트를 쿼리할 수도 있습니다. Chat API를 호출하면 정기적으로 이벤트를 검색하거나 서비스 중단으로 인해 구독에서 놓쳤을 수 있는 이벤트를 확인할 수 있습니다. Chat 이벤트를 수신하고 응답하는 방법에 대한 자세한 내용은 Chat 문서의 Chat 이벤트 작업을 참조하세요.

지원되는 Chat 이벤트

Google Workspace 구독을 사용하면 Chat에서 다음과 같은 유형의 변경사항에 관한 이벤트를 수신할 수 있습니다.

  • 스페이스에서 새로 작성, 업데이트 또는 삭제된 메시지
  • 메시지에 대한 새로운 반응 또는 삭제된 반응
  • 스페이스의 신규, 업데이트 또는 삭제된 멤버
  • 구독 중인 스페이스의 변경사항(예: 업데이트된 스페이스 이름 또는 설명)
  • 사용자의 참석 여부 변경
  • 사용자의 spaceReadState 또는 threadReadState가 변경됩니다.

이벤트를 모니터링할 수 있는 리소스

이벤트를 수신하려면 모니터링할 Chat 리소스를 지정해야 합니다. 이를 구독의 대상 리소스라고 합니다.

Google Workspace Events API는 Chat에 대해 다음 대상 리소스를 지원합니다.

대상 리소스 형식 제한사항
우주

//chat.googleapis.com/spaces/SPACE

여기서 SPACE는 Chat API space 리소스의 리소스 이름에 있는 ID입니다. 스페이스의 URL에서 또는 spaces.list() 메서드를 사용하여 ID를 가져올 수 있습니다.

 구독을 승인하는 Chat 사용자 또는 Chat 앱은 Google Workspace 또는 Google 계정을 통해 스페이스의 구성원이어야 합니다. 지원:
사용자의 모든 스페이스

//chat.googleapis.com/spaces/-

 구독은 사용자가 Google Workspace 또는 Google 계정을 통해 멤버로 있는 스페이스의 이벤트만 수신합니다. 사용자 인증만 지원합니다.
사용자

//cloudidentity.googleapis.com/users/USER

여기서 USER는 Chat API user 리소스의 리소스 이름에 있는 ID입니다. 자세한 내용은 Google Chat 사용자 식별 및 지정을 참고하세요.

구독은 구독을 승인한 사용자에 관한 이벤트만 수신합니다. 사용자는 다른 사용자를 대신하여 구독을 승인할 수 없습니다. 사용자 인증만 지원합니다.
고객

//admin.googleapis.com/customers/CUSTOMER

여기서 CUSTOMER는 고객 ID입니다. Chat 앱의 고객 도메인에 my_customer 별칭을 사용할 수도 있습니다.

구독은 고객 도메인에서 관리하는 모든 스페이스 및 사용자의 이벤트를 수신합니다. 관리자 승인이 필요한 앱 인증만 지원합니다.

구독을 만들기 위한 이벤트 유형

구독을 만들 때 eventTypes[] 필드를 사용하여 수신할 이벤트 유형을 지정합니다. 이벤트 유형은 google.workspace.APPLICATION.RESOURCE.VERSION.ACTION와 같은 CloudEvents 사양에 따라 형식이 지정됩니다.

예를 들어 Chat 스페이스에 참여하는 사용자에 관한 이벤트를 수신하려면 스페이스를 대상 리소스로 지정하고 이벤트 유형을 google.workspace.chat.membership.v1.created로 지정합니다. 특정 사용자가 스페이스에 참여하는 것에 관한 이벤트를 수신하려면 사용자를 대상 리소스로 지정하고 이벤트 유형을 google.workspace.chat.membership.v1.created로 지정합니다. 이벤트 작동 방식에 대한 자세한 내용은 Google Workspace 이벤트 구조를 참고하세요.

다음 표에는 스페이스 구독 및 사용자 구독에 지원되는 이벤트 유형이 나와 있습니다. 이벤트를 트리거하는 항목에 대한 예외는 제한사항을 참조하세요.

Event type(이벤트 유형) 형식 리소스 데이터
스페이스 구독  
메시지가 게시될 때

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 앱은 일괄 이벤트를 수신할 수도 있습니다. 일괄 이벤트는 짧은 시간 내에 발생하는 동일한 유형의 여러 이벤트를 나타내는 이벤트입니다. 일괄 이벤트의 페이로드에는 변경된 모든 리소스의 목록이 포함됩니다.

예를 들어 사용자가 스페이스에 동시에 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의 이벤트에 대한 이벤트 데이터와 페이로드 예시를 설명합니다.

Google Workspace 구독이 Chat에서 이벤트를 수신하면 data 필드에 이벤트의 페이로드가 포함됩니다. 이 페이로드에는 변경된 Google Workspace 리소스에 대한 정보가 포함되어 있습니다. 예를 들어 스페이스의 멤버십 이벤트를 구독한 경우 이러한 이벤트의 페이로드에는 변경된 spaces.membership 리소스에 관한 정보가 포함됩니다.

이벤트 페이로드의 리소스 데이터

구독을 만들 때 페이로드에 리소스에 대한 세부정보를 포함할지 아니면 리소스 이름만 포함할지 지정할 수 있습니다. 예를 들어 Chat 스페이스의 멤버에 관한 이벤트를 수신하려면 이벤트 페이로드에서 수신할 멤버십 리소스의 필드를 지정합니다.

다음 표에서는 Chat 스페이스 spaces/AAAABBBBBB 구독에 대한 JSON 페이로드의 예를 보여줍니다. 구독이 수신하는 각 이벤트의 경우 페이로드가 이벤트의 data 필드에 표시됩니다.

예 Event type(이벤트 유형) 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 SKU 라이선스가 하나 이상 있어야 합니다.
  • Chat 앱은 특정 Google Workspace 조직에 대해 하나의 고객 구독만 만들 수 있습니다. Google Workspace 조직은 서로 다른 Chat 앱에서 만든 고객 구독을 총 5개까지 보유할 수 있습니다.

고객 구독의 경우 이벤트 전송은 다음 일반 규칙을 따릅니다.

  • 스페이스 이벤트: Google Workspace 조직에서 관리하는 스페이스에서 이벤트가 발생하는 경우에만 전송됩니다.
  • 사용자 이벤트: Google Workspace 조직에 속한 사용자에게 이벤트가 발생하는 경우에만 전송됩니다.

이러한 규칙의 유일한 예외는 멤버십 이벤트입니다. 구독은 조직에서 관리하는 스페이스와 외부 조직에서 관리하는 스페이스 모두에서 멤버십 이벤트를 수신할 수 있지만, 전달 방식은 스페이스를 관리하는 조직에 따라 다릅니다.

Google Workspace 조직에서 관리하는 스페이스

Google Workspace 조직에서 관리하는 스페이스에서 멤버십 변경이 발생하면 스페이스 이벤트로 전송됩니다.

스페이스 이벤트의 리소스 이름은 다음 형식을 사용합니다.

spaces/{spaceId}/spaceEvents/{spaceEventId}

외부 조직에서 관리하는 스페이스

Google Workspace 조직에서 관리하는 사용자의 멤버십이 외부 조직에서 관리하는 스페이스 (예: 외부 이름이 지정된 스페이스 또는 외부 사용자가 만든 채팅 메시지)에서 변경되면 구독에서 이 이벤트를 사용자 이벤트로 수신합니다.

사용자 이벤트의 리소스 이름은 다음 형식을 사용합니다.

users/{userId}/userEvents/{userEventId}