Google Chat 인터페이스 빌드

이 페이지에서는 Google Chat을 확장하는 Google Workspace 부가기능의 사용자 인터페이스(UI)를 빌드하는 방법을 간략히 설명합니다.

Google Chat에서 부가기능은 사용자에게 Google Chat 앱으로 표시됩니다. 자세한 내용은 Google Chat 확장 개요를 참고하세요.

Chat 앱의 인터페이스를 빌드하려면 다음 부가기능 구성요소를 사용합니다.

  • 트리거: Google Chat 사용자가 Chat 앱을 호출하는 방법(예: 스페이스에 추가하거나 메시지 보내기)입니다.
  • 이벤트 객체: Chat 앱이 트리거 또는 UI 상호작용에서 수신하는 데이터입니다.
  • 작업: Chat 앱이 메시지 전송 또는 카드 기반 사용자 인터페이스 반환과 같이 상호작용에 응답하는 방법입니다.
Chat 앱이 스페이스에 추가됨 트리거에서 이벤트 객체 수신
그림 1: 사용자가 스페이스에 Chat 앱을 추가하면 스페이스에 추가됨 트리거가 실행되고 이벤트 객체가 전송됩니다. 메시지로 응답하기 위해 Chat 앱은 이벤트 객체를 처리하고 메시지를 만드는 작업을 반환합니다.

Chat 앱은 다음 인터페이스에서 카드를 빌드하고 표시할 수 있습니다.

  • 텍스트, 정적 또는 양방향 카드, 버튼을 포함할 수 있는 메시지
  • 대화상자: 새 창에서 열리고 일반적으로 사용자에게 정보를 제출하라는 메시지를 표시하는 카드입니다.
  • 외부 서비스에 대한 정보를 미리 볼 수 있는 카드인 링크 미리보기

트리거

이 섹션에서는 Google Workspace 부가기능이 Chat에서 사용하는 트리거를 설명합니다.

트리거는 사용자가 @멘션 또는 앱 명령어를 사용하는 등 Chat UI를 사용하여 Chat 앱을 호출하는 특정 방법입니다.

다음 표에는 Chat 트리거, 설명, Chat 앱이 일반적으로 응답하는 방식이 나와 있습니다.

트리거 설명 일반적인 응답
스페이스에 추가됨

사용자가 스페이스에 Chat 앱을 추가하거나 Google Workspace 관리자가 조직의 사용자를 위해 채팅 메시지 스페이스에 Chat 앱을 설치합니다. 관리자가 설치한 Chat 앱에 관해 알아보려면 Google Workspace 관리자 도움말 문서의 도메인에 Marketplace 앱 설치하기를 참고하세요.

 Chat 앱은 기능과 스페이스의 사용자가 앱과 상호작용하는 방법을 설명하는 온보딩 메시지를 전송합니다.
메시지

사용자가 다음 중 한 가지 방법으로 메시지에서 Chat 앱과 상호작용합니다.

  • Chat 앱으로 채팅 메시지 (DM) 스페이스에 메시지를 보냅니다.
  • 모든 유형의 스페이스에서 Chat 앱을 @멘션합니다.
  • 링크 미리보기의 URL 패턴과 일치하는 링크가 포함된 메시지를 전송합니다.
  • selectionInput 위젯의 멀티셀렉션 메뉴에 텍스트를 입력합니다.
 채팅 앱은 메시지의 콘텐츠를 기반으로 응답합니다. 예를 들어 Chat 앱은 /about 명령어에 Chat 앱에서 실행할 수 있는 작업을 설명하는 메시지로 응답합니다.
스페이스에서 삭제됨

사용자가 스페이스에서 Chat 앱을 삭제하거나 Google Workspace 관리자가 조직의 사용자를 위해 Chat 앱을 제거합니다.

관리자가 설치한 Chat 앱은 사용자가 삭제할 수 없습니다. 사용자가 이전에 Chat 앱을 설치한 경우 Google Workspace 관리자가 제거하려고 시도해도 Chat 앱은 계속 설치된 상태로 유지됩니다.

 Chat 앱은 스페이스에 구성된 수신 알림 (예: Webhook 삭제)을 삭제하고 내부 저장소를 정리합니다. 채팅 앱은 더 이상 스페이스의 구성원이 아니므로 이 트리거에 메시지로 응답할 수 없습니다.
앱 명령어

사용자가 Chat 앱에서 빠른 명령어 또는 슬래시 명령어를 사용합니다.

 Chat 앱이 명령어에 응답합니다. 예를 들어 메시지로 답장하거나 대화상자를 엽니다.

다른 Google Workspace 부가기능과 달리 이러한 트리거의 콜백 함수는 Google Chat API를 사용하여 구성해야 합니다. 자세한 내용은 Google Chat 앱 구성을 참고하세요.

트리거에 응답하려면 다음 가이드를 참고하세요.

이벤트 객체

이 섹션에서는 Chat 이벤트 객체의 모든 요소를 정의하고 설명합니다. 자세한 내용은 이벤트 객체를 참고하세요.

이벤트 객체
commonEventObject object (CommonEventObject)
호스트 애플리케이션과 관계없이 모든 이벤트 객체에 공통적인 정보를 포함하는 객체입니다.
chat object (Chat)
Chat 상호작용에 관한 모든 정보를 포함하는 객체입니다.

채팅

채팅
chat.user object (User)
Chat 앱과 상호작용한 Chat 사용자입니다.
chat.space object (Space)
사용자가 Chat 앱과 상호작용한 Chat 스페이스입니다.
chat.eventTime

string (Timestamp format)

상호작용이 발생한 시간입니다.

통합 필드 payload.

payload는 다음 중 하나여야 합니다.
chat.messagePayload

object (MessagePayload)

Chat 앱이 메시지 트리거에서 수신하는 페이로드입니다.
chat.addedToSpacePayload

object (AddedToSpacePayload)

Chat 앱이 스페이스에 추가됨 트리거에서 수신하는 페이로드입니다.
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

Chat 앱이 스페이스에서 삭제됨 트리거에서 수신하는 페이로드입니다.
chat.buttonClickedPayload

object (ButtonClickedPayload)

사용자가 메시지 또는 카드에서 버튼을 클릭할 때 Chat 앱이 수신하는 페이로드입니다. 사용자가 버튼을 클릭하여 정보를 제출하면 commonEventObject.formInputs 객체에 사용자로부터 수집된 값이 포함됩니다. 자세한 내용은 Google Chat 사용자로부터 정보 수집을 참고하세요.
chat.widgetUpdatedPayload

object (WidgetUpdatedPayload)

사용자가 selectionInput 위젯의 멀티셀렉션 메뉴에 텍스트를 입력할 때 Chat 앱이 수신하는 페이로드입니다. 채팅 앱은 이 이벤트 객체를 사용하여 동적 데이터 소스의 추천 항목을 채울 수 있습니다. 예를 들어 외부 데이터 소스에서 지원 케이스를 채우기 위해 채팅 앱은 사용자가 메뉴에 입력한 내용을 기반으로 데이터 소스를 쿼리한 다음 일치하는 지원 케이스를 선택 가능한 항목으로 반환할 수 있습니다.

CommonEventObject.parameters['autocomplete_widget_query'] 객체에는 사용자가 메뉴에 입력하는 문자열 값이 포함됩니다.

chat.appCommandPayload

object (AppCommandPayload)

사용자가 Chat 앱의 명령어를 사용할 때 Chat 앱에서 수신하는 페이로드입니다.

페이로드

상호작용 유형에 따라 이벤트에는 하나 이상의 Chat API 리소스가 포함된 페이로드가 포함됩니다.

메시지 페이로드
MessagePayload
chat.messagePayload.message object (Message)
이벤트를 트리거한 Chat 메시지입니다.
chat.messagePayload.space object (Space)
사용자가 Chat 앱을 호출한 메시지를 보낸 Chat 스페이스입니다.

스페이스 페이로드에 추가됨
AddedToSpacePayload
chat.addedToSpacePayload.space object (Space)
사용자가 Chat 앱을 추가하거나 설치한 Chat 스페이스입니다.

관리자가 Chat 앱을 설치하면 space.adminInstalled 필드가 true로 설정됩니다.

chat.addedToSpacePayload.interactionAdd boolean
사용자가 메시지를 사용하여 Chat 앱을 스페이스에 추가하는지 여부입니다. 예를 들어 Chat 앱을 @멘션하거나 슬래시 명령어를 사용하는 경우입니다. true인 경우 Chat은 메시지에 관한 정보가 포함된 messagePayload와 함께 다른 이벤트 객체를 전송합니다.

스페이스 페이로드에서 삭제됨
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
사용자가 Chat 앱을 삭제했거나 제거한 Chat 스페이스입니다.

관리자가 Chat 앱을 제거하면 space.adminInstalled 필드가 false로 설정됩니다.

버튼 클릭 페이로드
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
사용자가 클릭한 버튼이 포함된 채팅 메시지입니다.
chat.buttonClickedPayload.space object (Space)
사용자가 Chat 앱 메시지에서 버튼을 클릭한 Chat 스페이스입니다.
chat.buttonClickedPayload.isDialogEvent boolean
사용자가 버튼을 클릭하여 대화상자와 상호작용했는지 여부입니다.
chat.buttonClickedPayload.dialogEventType enum (DialogEventType)
isDialogEvent이 true인 경우 대화상자의 상호작용 유형입니다.

Enum DialogEventType.

dialogEventType 값은 다음 중 하나여야 합니다.
TYPE_UNSPECIFIED 기본값 지정되지 않았습니다.
REQUEST_DIALOG 사용자가 대화상자를 요청합니다. 예를 들어 슬래시 명령어를 사용하거나 메시지의 버튼을 클릭합니다.
SUBMIT_DIALOG 사용자가 대화상자 내의 대화형 요소를 클릭합니다. 예를 들어 사용자가 대화상자에 정보를 입력하고 버튼을 클릭하여 정보를 제출합니다.

위젯 업데이트 페이로드
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
상호작용이 발생한 Chat 스페이스입니다.

앱 명령어 페이로드
AppCommandPayload
chat.appCommandPayload.appCommandMetadata object (AppCommandMetadata)
사용자가 사용한 명령어와 명령어를 트리거한 방법에 관한 메타데이터입니다.
chat.appCommandPayload.space object (Space)
사용자가 명령어를 사용한 Chat 공간입니다.
chat.appCommandPayload.thread object (Thread)
대화가 대화목록에서 발생한 경우 사용자가 명령어를 사용한 채팅 대화목록입니다.
chat.appCommandPayload.message object (Message)
사용자가 슬래시 명령어와 함께 보낸 메시지입니다.
chat.appCommandPayload.configCompleteRedirectUri string
명령어에 승인 또는 구성이 필요한 경우 사용자가 Google Chat 외부에서 프로세스를 완료한 후 리디렉션할 URL입니다.
chat.appCommandPayload.isDialogEvent boolean
명령어가 대화상자를 여는지 여부입니다.
chat.appCommandPayload.dialogEventType enum (DialogEventType)
대화상자와의 상호작용 유형입니다.

Enum DialogEventType.

dialogEventType 값은 다음 중 하나여야 합니다.
TYPE_UNSPECIFIED 기본값 지정되지 않았습니다.
REQUEST_DIALOG 사용자가 대화상자를 요청합니다. 예를 들어 슬래시 명령어를 사용하거나 메시지의 버튼을 클릭합니다.
SUBMIT_DIALOG 사용자가 대화상자 내의 대화형 요소를 클릭합니다. 예를 들어 사용자가 대화상자에 정보를 입력하고 버튼을 클릭하여 정보를 제출합니다.
앱 명령어 메타데이터
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string (int64 format)

명령어 ID입니다.
chat.appCommandPayload.appCommandMetadata.appCommandType enum (AppCommandType)
명령어 유형입니다.

Enum AppCommandType.

AppCommandType 값은 다음 중 하나여야 합니다.
APP_COMMAND_TYPE_UNSPECIFIED 기본값 지정되지 않았습니다.
SLASH_COMMAND 사용자가 슬래시 /로 시작하는 메시지를 보내 명령어를 사용합니다.

채팅 작업

이 섹션에서는 채팅 앱이 부가기능 작업을 사용하여 사용자 상호작용에 응답하는 방법을 설명합니다.

부가기능 작업으로 응답하려면 Chat 앱이 30초 이내에 응답해야 하며 응답은 상호작용이 발생한 스페이스에 게시되어야 합니다. 그러지 않으면 Chat 앱에서 인증을 설정하고 Google Chat API를 호출하여 응답해야 합니다.

채팅 앱은 다양한 방식으로 상호작용을 처리하고 응답할 수 있습니다. 대부분의 경우 Chat 앱은 메시지로 답장합니다. 채팅 앱은 데이터 소스에서 일부 정보를 조회하거나 이벤트 객체 정보를 기록하거나 그 밖의 다른 모든 작업을 할 수도 있습니다. 이 처리 동작은 기본적으로 Google Chat 앱을 정의하는 것입니다.

사용자 상호작용에 응답하려면 Chat 앱이 상응하는 이벤트 객체를 처리하고 다음 JSON 객체 중 하나를 반환해야 합니다.

Chat 앱에서 원하는 응답 반품에 필요한 조치
메시지 보내기 또는 업데이트하기 DataActions
대화상자를 열거나, 업데이트하거나, 닫습니다. RenderActions
카드 또는 대화상자에서 정보를 수집하려면 사용자가 다중 선택 메뉴에 입력한 내용을 기반으로 선택 항목을 추천합니다. RenderActions
Chat 사용자가 스페이스에서 보낸 메시지의 링크 미리보기 DataActions

Google Chat API를 사용하여 응답

Chat 앱은 부가기능 작업을 반환하는 대신 Google Chat API를 사용하여 상호작용에 응답해야 할 수 있습니다. 예를 들어 Chat 앱은 다음 작업을 실행하려면 Google Chat API를 호출해야 합니다.

  • 30초 후에 상호작용에 응답합니다.
  • 상호작용이 발생한 스페이스 외부에서 작업을 실행합니다.
  • 부가기능 작업으로 사용할 수 없는 작업을 Chat에서 실행합니다. 예를 들어 사용자 또는 Chat 앱이 참여 중인 스페이스를 나열하거나 스페이스에 사용자를 추가합니다.
  • Chat 사용자를 대신하여 작업을 실행합니다 (사용자 인증 필요).

Chat API 인증 및 호출에 관해 자세히 알아보려면 Chat API 개요를 참고하세요.