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

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

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

상호작용 이벤트의 형식

사용자는 다양한 방법으로 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개)

메시지

이 상호작용 이벤트는 사용자가 다음과 같은 메시지를 Chat 앱에 보내는 경우를 나타냅니다.

• Chat 앱을 사용한 채팅 메시지 (DM) 스페이스의 모든 메시지
• 사용자가 Chat 앱을 @멘션하거나 슬래시 명령어 중 하나를 사용하는 다인용 스페이스의 메시지.
• 채팅 앱의 링크 미리보기를 구성한 경우 사용자가 구성된 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": "[e-mail]"
    },
    "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": "[e-mail]"
  }
}

스페이스에 추가됨

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

다음 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": "[e-mail]"
  }
}

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": "[e-mail]"
  }
}

스페이스에서 삭제됨

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

다음 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": "[e-mail]"
  }
}

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": "[e-mail]"
  }
}

카드 클릭됨

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

상호작용 이벤트를 수신하려면 버튼이 채팅 앱과의 다른 상호작용을 트리거해야 합니다. 예를 들어 사용자가 웹사이트 링크를 여는 버튼을 클릭했지만 다음 예에서 상호작용 이벤트를 수신하는 경우 채팅 앱이 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": "[e-mail]",
    "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",
}

앱 홈 메시지

이 상호작용 이벤트는 사용자가 채팅 앱에서 채팅 메시지를 열고 채팅 앱 홈 메시지를 받았음을 나타냅니다.

다음 JSON 예는 APP_HOME 상호작용 이벤트의 요청 본문을 보여줍니다.

{
  "chat": {
    "type": "APP_HOME",
    "user": {
      "name": "users/12345678901234567890",
      "type": "HUMAN",
      "email": "[e-mail]",
      "domainId": "ABCDEFG"
    },
    "space": {
      "name": "spaces/AAAAAAAAAAA",
      "singleUserBotDm": true,
      "spaceType": "DIRECT_MESSAGE"
    }
  },
  "commonEventObject": {
    "invokedFunction": "onAppHome",
    "userLocale": "en",
    "hostApp": "CHAT"
  }
}

앱 홈 메시지로 양식 제출

이 상호작용 이벤트는 사용자가 채팅 앱 홈 메시지를 통해 양식 정보를 제출했음을 나타냅니다.

다음 JSON 예는 SUBMIT_FORM 상호작용 이벤트의 요청 본문을 보여줍니다.

{
  "commonEventObject": {
    "userLocale": "en",
    "invokedFunction": "onSubmitFunction",
    "formInputs": {
      "username": {
        "": {
          "stringInputs": {
            "value": [
              "Ira"
            ]
          }
        }
      }
    },
    "hostApp": "CHAT"
  },
  "chat": {
    "type": "SUBMIT_FORM",
    "space": {
      "name": "spaces/AAAAAAAAAAA",
      "spaceType": "DIRECT_MESSAGE",
      "singleUserBotDm": true
    },
    "user": {
      "type": "HUMAN",
      "name": "123456789"
    }
  }
}

관련 주제

상호작용 이벤트의 페이로드를 처리하고 응답을 반환하는 방법을 알아보려면 다음 가이드를 참조하세요.

• 카드 메시지 보내기
• 문자 메시지 보내기
• 앱 홈 카드 메시지 보내기
• 대화형 대화상자 열기
• 미리보기 링크
• 카드에서 사용자의 양식 데이터 입력 읽기
• 슬래시 명령어 설정