이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Google Chat 앱 상호작용 이벤트 유형

이 페이지에서는 Google Chat 앱이 Google Chat에서 수신할 수 있는 상호작용 이벤트 유형을 설명합니다.

상호작용 이벤트를 수신하도록 채팅 앱을 구성하려면 채팅 앱과의 상호작용 수신 및 응답을 참고하세요.

상호작용 이벤트의 형식

사용자는 다양한 방법으로 채팅 앱과 상호작용할 수 있습니다. 상호작용 유형별로 Google Chat은 서로 다른 유형의 상호작용 이벤트를 전송합니다.

메시지: 사용자가 채팅 앱에 메시지를 보내거나 스페이스에서 채팅 앱을 호출합니다.
스페이스에 추가됨: 사용자가 채팅 앱을 스페이스에 추가합니다.
스페이스에서 삭제됨: 사용자가 스페이스에서 채팅 앱을 삭제합니다.
카드 클릭됨: 사용자가 채팅 앱에서 보낸 양방향 카드 또는 대화상자를 클릭합니다.

사용자가 채팅 앱과 상호작용할 때마다 Google Chat은 상호작용을 나타내는 JSON 페이로드인 요청 본문과 함께 상호작용 이벤트를 전송합니다. 이 이벤트 페이로드에는 모든 유형의 상호작용 이벤트에 공통된 요소뿐 아니라 특정 이벤트 유형과 관련된 요소도 포함됩니다.

상호작용 이벤트의 필드에 관한 자세한 내용은 Google Chat API의 Event 참조 문서를 확인하세요.

일반 필드

다음 필드는 항상 상호작용 이벤트의 페이로드에 제공됩니다.

필드	설명
`type`	채팅 앱이 수신하는 이벤트의 유형입니다(예: `MESSAGE` 또는 `ADDED_TO_SPACE`).
`eventTime`	이벤트가 전달된 시간을 나타내는 타임스탬프입니다.
`common`	언어 또는 플랫폼과 같은 사용자의 클라이언트에 대한 정보를 나타냅니다.

상호작용 이벤트 유형별 필드

이벤트 유형에 따라 페이로드에 다음과 같은 추가 필드가 포함될 수 있습니다.

필드	설명	이벤트 유형
`message`	이벤트와 관련된 메시지입니다.	`MESSAGE`, `ADDED_TO_SPACE`, `CARD_CLICKED`
`space`	이벤트와 관련된 공간입니다.	`MESSAGE`, `ADDED_TO_SPACE`, `REMOVED_FROM_SPACE`, `CARD_CLICKED`:
`user`	이벤트와 관련된 사용자입니다. 사용자는 항상 사람입니다 (채팅 앱이 아님).	`MESSAGE`, `ADDED_TO_SPACE`, `REMOVED_FROM_SPACE`, `CARD_CLICKED`:
`action`	사용자가 양방향 카드 또는 대화상자를 클릭할 때 트리거되는 함수입니다.	`CARD_CLICKED`

이벤트 페이로드 예시

이 섹션에서는 상호작용 이벤트를 트리거하는 요소를 설명하고 다음 각 이벤트 유형에 대한 JSON 페이로드 예시를 제공합니다.

메시지 (MESSAGE)
스페이스에 추가됨 (ADDED_TO_SPACE개)
스페이스에서 삭제됨 (REMOVED_FROM_SPACE개)
카드 클릭됨 (CARD_CLICKED개)

메시지

이 상호작용 이벤트는 사용자가 채팅 앱에 메시지를 보내는 시점을 나타냅니다. 예를 들면 다음과 같습니다.

채팅 앱을 사용한 채팅 메시지 (DM) 스페이스의 모든 메시지
다자간 스페이스에서 사용자가 채팅 앱을 @멘션하거나 슬래시 명령어 중 하나를 사용하는 메시지
채팅 앱의 링크 미리보기를 구성한 경우 사용자가 구성된 URL 패턴과 일치하는 링크가 포함된 메시지를 게시합니다.

다음 JSON 예는 사용자가 여러 사용자가 있는 스페이스에서 채팅 앱을 @멘션하는 MESSAGE 상호작용 이벤트를 보여줍니다.

{
  "type": "MESSAGE",
  "eventTime": {
      "seconds": 1691187414,
      "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "SPACE"
  },
  "message": {
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "sender": {
      "name": "users/12345678901234567890",
      "displayName": "Izumi",
      "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
      "email": "izumi@example.com"
    },
    "createTime": {
      "seconds": 1691187386,
      "nanos": 954319000
    },
    "text": "@TestBot Create ticket.",
    "argumentText": " Create ticket.",
    "thread": {
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB",
      "threadKey": "custom-thread-ID"
    },
    "annotations": [
      {
        "length": 8,
        "startIndex": 0,
        "userMention": {
          "type": "MENTION",
          "user": {
            "avatarUrl": "https://.../avatar.png",
            "displayName": "TestBot",
            "name": "users/1234567890987654321",
            "type": "BOT"
          }
        },
        "type": "USER_MENTION"
      }
    ],
    "attachment": [
      {
        "name": "spaces/5o6pDgAAAAE/messages/Ohu1LlUVcS8.Ohu1LlUVcS8/attachments/AATUf-Iz7d8kySEdRRZd-dznqBk3",
        "content_name": "solar.png",
        "content_type": "image/png",
        "drive_data_ref": {
          "drive_file_id": "H1HqaqRuH2Pfd_TOa1fF2_ltwDlV_yKRrr"
        },
        "source": "DRIVE_FILE"
      }
    ]
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

스페이스에 추가됨

이 상호작용 이벤트는 채팅 앱이 스페이스에 추가되었음을 나타냅니다. 일반적으로 앱은 스페이스의 새 스레드에 일종의 환영 메시지를 게시하여 이 상호작용 이벤트에 응답합니다.

다음 JSON 예는 사용자가 채팅 앱을 스페이스에 추가할 때 ADDED_TO_SPACE 상호작용 이벤트의 요청 본문을 보여줍니다.

{
  "type": "ADDED_TO_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "SPACE",
    "adminInstalled": "false"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Google Workspace 관리자가 설치함

또한 ADDED_TO_SPACE 상호작용 이벤트는 Google Workspace 관리자가 조직 내 사용자를 위해 Chat 앱을 설치했음을 나타낼 수도 있습니다.

관리자는 채팅 앱과 사용자 간의 채팅 메시지 전용 채팅 앱만 설치할 수 있습니다. 설치된 앱은 사용자의 채팅 메시지 패널에 표시됩니다. 관리자가 Chat 앱을 설치하면 사용자는 제거할 수 없습니다. 관리자가 설치한 Chat 앱에 대한 자세한 내용은 Google Workspace 관리자 도움말 문서의 도메인에 Marketplace 앱 설치하기를 참조하세요.

다음 JSON 예시는 Google Workspace 관리자가 사용자의 Chat 앱을 설치할 때 ADDED_TO_SPACE 상호작용 이벤트의 요청 본문을 보여줍니다. 관리자가 채팅 앱을 설치했으므로 adminInstalled가 true로 설정됩니다.

{
  "type": "ADDED_TO_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "DIRECT_MESSAGE",
    "adminInstalled": "true"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

스페이스에서 삭제됨

이 상호작용 이벤트는 채팅 앱이 스페이스에서 삭제되었음을 나타냅니다. 채팅 앱은 이미 삭제되었으므로 이 이벤트에 대한 메시지로 응답하지 않습니다.

다음 JSON 예는 사용자가 스페이스에서 채팅 앱을 삭제할 때 REMOVED_FROM_SPACE 상호작용 이벤트의 요청 본문을 보여줍니다.

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "spaceType": "SPACE",
    "adminInstalled": "false"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Google Workspace 관리자가 제거함

REMOVED_FROM_SPACE 상호작용 이벤트는 Google Workspace 관리자가 조직 내 사용자의 Chat 앱을 제거했음을 나타낼 수도 있습니다. 제거하면 채팅 앱이 더 이상 사용자의 채팅 메시지 패널에 표시되지 않습니다.

사용자가 관리자보다 먼저 채팅 앱을 설치했다면 사용자의 채팅 앱은 설치된 상태로 유지됩니다. 이 경우 채팅 앱이 여전히 설치되어 있으므로 채팅 앱이 REMOVED_FROM_SPACE 상호작용 이벤트를 수신하지 않습니다.

다음 JSON 예시는 Google Workspace 관리자가 사용자의 Chat 앱을 제거할 때 REMOVED_FROM_SPACE 상호작용 이벤트의 요청 본문을 보여줍니다. 관리자가 Chat 앱을 제거했으므로 adminInstalled가 true로 설정됩니다.

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "spaceType": "DIRECT_MESSAGE",
    "adminInstalled": "true"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

카드 클릭됨

이 상호작용 이벤트는 사용자가 카드 메시지 또는 대화상자에서 버튼을 클릭했음을 나타냅니다.

상호작용 이벤트를 수신하려면 버튼은 채팅 앱과의 다른 상호작용을 트리거해야 합니다. 예를 들어 사용자가 웹사이트 링크를 여는 버튼을 클릭하지만 다음 예에서 상호작용 이벤트를 수신하는 경우 채팅 앱은 CARD_CLICKED 상호작용 이벤트를 수신하지 않습니다.

사용자가 카드의 Send feedback 버튼을 클릭하면 사용자가 정보를 입력할 수 있는 대화상자가 열립니다.
사용자가 카드 또는 대화상자에 정보를 입력한 후 Submit 버튼을 클릭합니다.

다음 JSON 예는 사용자가 수신 지원 티켓을 할당하는 카드 메시지의 버튼을 클릭할 때 CARD_CLICKED 상호작용 이벤트의 요청 본문을 보여줍니다.

{
  "type": "CARD_CLICKED",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "common": {
    "userLocale": "en",
    "hostApp": "CHAT",
    "invokedFunction": "doAssignTicket",
    "timeZone": {
      "offset": -25200000,
      "id": "America/Los_Angeles"
    }
  },
  "action": {
    "actionMethodName": "doAssignTicket"
  },
  "message": {
    "cards": [
      {
        "header": {
          "title": "Incoming support ticket."
        },
        "sections": [
          {
            "widgets": [
              {
                "textParagraph": {
                  "text": "Incoming support ticket #12345 is unassigned and needs your attention."
                }
              },
              {
                "buttons": [
                  {
                    "textButton": {
                      "onClick": {
                        "action": {
                          "actionMethodName": "doAssignTicket"
                        }
                      },
                      "text": "Assign to me"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    ],
    "sender": {
      "avatarUrl": "https://www.example.com/images/chat-app-icon.png",
      "displayName": "Support Chat app",
      "name": "users/98765432109876543210",
      "type": "BOT"
    },
    "createTime": {
      "seconds": 1691187386,
      "nanos": 954319000
    },
    "retentionSettings": {
      "state": "PERMANENT"
    },
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "thread": {
      "retentionSettings": {
        "state": "PERMANENT"
      },
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB"
    },
    "messageHistoryState": "HISTORY_ON",
    "space": {
      "spaceThreadingState": "GROUPED_MESSAGES",
      "spaceType": "SPACE",
      "displayName": "Customer Support Superstars",
      "name": "spaces/AAAAAAAAAAA",
      "spaceHistoryState": "HISTORY_ON",
      "type": "ROOM",
      "threaded": true
    }
  },
  "user": {
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "displayName": "Izumi",
    "name": "users/12345678901234567890",
    "type": "HUMAN",
    "email": "izumi@example.com",
    "domainId": "ABCDEFG"
  },
  "space": {
    "spaceThreadingState": "GROUPED_MESSAGES",
    "spaceType": "SPACE",
    "displayName": "Customer Support Superstars",
    "name": "spaces/AAAAAAAAAAA",
    "spaceHistoryState": "HISTORY_ON",
    "type": "ROOM",
    "threaded": true
  }
}

대화상자 카드 클릭수

사용자가 대화상자와 상호작용할 때 CARD_CLICKED 상호작용 이벤트의 페이로드에는 다음과 같은 추가 필드가 포함됩니다.

isDialogEvent: 대화상자가 포함된 상호작용 이벤트의 경우 true로 설정합니다.
DialogEventType: 대화상자와의 상호작용 유형입니다(사용자가 대화상자를 열거나 제출하는 여부 또는 대화상자를 취소하는 경우 포함).

다음 JSON 예는 CARD_CLICKED 상호작용 이벤트의 요청 본문 일부를 보여줍니다. 이 예에서는 사용자가 채팅 앱에 정보를 제출하는 대화상자의 버튼을 클릭했습니다.

{
  "type": "CARD_CLICKED",
  ...
  "isDialogEvent": true,
  "dialogEventType": "SUBMIT_DIALOG",
}