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

상호작용 이벤트 수신 및 응답

이 페이지에서는 Google Chat 앱이 Google Chat 앱 상호작용 이벤트라고도 하는 사용자 상호작용을 수신하고 이에 응답하는 방법을 설명합니다.

이 페이지에서는 다음 작업을 수행하는 방법을 설명합니다.

상호작용 이벤트를 수신하도록 Chat 앱을 구성합니다.
인프라에서 상호작용 이벤트를 처리합니다.
적절한 경우 상호작용 이벤트에 응답합니다.

기본 요건

Google Chat에 액세스할 수 있는 Business 또는 Enterprise Google Workspace 계정
Google Cloud 프로젝트를 만듭니다.
OAuth 동의 화면 구성
Google Chat API를 사용 설정합니다.

상호작용 이벤트 유형

Google Chat 앱 상호작용 이벤트는 사용자가 Chat 앱을 호출하거나 상호작용하기 위해 취하는 모든 작업을 나타냅니다(예: Chat 앱을 @멘션하거나 스페이스에 추가).

사용자가 Chat 앱과 상호작용하면 Google Chat은 Chat 앱에 상호작용 이벤트를 전송합니다. 이 이벤트는 Chat API에서 Event 유형으로 표시됩니다. Chat 앱은 이벤트를 사용하여 상호작용을 처리하고 선택적으로 메시지로 응답할 수 있습니다.

각 사용자 상호작용 유형에 대해 Google Chat은 다양한 유형의 상호작용 이벤트를 전송하여 Chat 앱이 각 이벤트 유형을 적절하게 처리하도록 지원합니다. 상호작용 이벤트 유형은 eventType 객체를 사용하여 표시됩니다.

예를 들어 Google Chat은 사용자가 스페이스에 Chat 앱을 추가하는 모든 상호작용에 이벤트 유형 ADDED_TO_SPACE를 사용하여 Chat 앱이 즉시 스페이스에서 환영 메시지로 응답할 수 있도록 합니다.

채팅 앱에서 환영 메시지를 게시합니다. — **그림 1**: 사용자가 스페이스에 채팅 앱을 추가하면 채팅 앱은 채팅 앱이 스페이스에 환영 메시지를 보내기 위해 처리하는 `ADDED_TO_SPACE` 상호작용 이벤트를 수신합니다.

다음 표는 일반적인 사용자 상호작용, 채팅 앱이 수신하는 상호작용 이벤트 유형, 채팅 앱의 일반적인 응답 방식을 보여줍니다.

사용자 상호작용	`eventType`	Chat 앱의 일반적인 응답
사용자가 채팅 앱에 메시지를 보냅니다. 예를 들어 채팅 앱을 @멘션하거나 슬래시 명령어를 사용합니다.	`MESSAGE`	채팅 앱은 메시지 내용을 기반으로 응답합니다. 예를 들어 채팅 앱은 슬래시 명령어 `/about`에 채팅 앱이 할 수 있는 작업을 설명하는 메시지로 답장합니다.
사용자가 스페이스에 Chat 앱을 추가합니다.	`ADDED_TO_SPACE`	Chat 앱은 스페이스의 사용자가 앱과 상호작용하는 방법과 앱의 기능을 설명하는 온보딩 메시지를 전송합니다.
사용자가 스페이스에서 채팅 앱을 삭제합니다.	`REMOVED_FROM_SPACE`	채팅 앱은 스페이스에 구성된 수신 알림을 삭제하고 (예: 웹훅 삭제) 내부 저장소를 정리합니다.
사용자가 채팅 앱 메시지, 대화상자 또는 홈페이지의 카드에 있는 버튼을 클릭합니다.	`CARD_CLICKED`	Chat 앱은 사용자가 제출한 데이터를 처리하고 저장하거나 다른 카드를 반환합니다.
사용자가 1:1 메시지에서 홈 탭을 클릭하여 Chat 앱의 홈페이지를 엽니다.	`APP_HOME`	채팅 앱은 홈페이지에서 정적 또는 양방향 카드를 반환합니다.
사용자가 Chat 앱의 홈페이지에서 양식을 제출합니다.	`SUBMIT_FORM`	Chat 앱은 사용자가 제출한 데이터를 처리하고 저장하거나 다른 카드를 반환합니다.
사용자가 빠른 명령어를 사용하여 명령어를 호출합니다.	`APP_COMMAND`	Chat 앱은 호출된 명령어를 기반으로 응답합니다. 예를 들어 Chat 앱은 정보 명령어에 Chat 앱이 할 수 있는 작업을 설명하는 메시지로 답장합니다.

지원되는 모든 상호작용 이벤트를 보려면 EventType 참조 문서를 참고하세요.

대화상자의 상호작용 이벤트

채팅 앱이 대화상자를 여는 경우 상호작용 이벤트에는 응답을 처리하는 데 사용할 수 있는 다음 추가 정보가 포함됩니다.

isDialogEvent는 true으로 설정됩니다.
DialogEventType는 상호작용이 대화상자를 열거나, 대화상자에서 정보를 제출하거나, 대화상자를 닫는지 여부를 명확히 합니다.

다음 표에는 대화상자와의 일반적인 상호작용, 해당 대화상자 이벤트 유형, 채팅 앱이 일반적으로 응답하는 방식에 관한 설명이 나와 있습니다.

대화상자와의 사용자 상호작용	대화상자 이벤트 유형	일반적인 응답
사용자가 대화상자 요청을 트리거합니다. 예를 들어 슬래시 명령어를 사용하거나 메시지에서 버튼을 클릭합니다.	`REQUEST_DIALOG`	Chat 앱에서 대화상자를 엽니다.
사용자가 버튼을 클릭하여 대화상자에 정보를 제출합니다.	`SUBMIT_DIALOG`	채팅 앱은 다른 대화상자로 이동하거나 대화상자를 닫아 상호작용을 완료합니다.
사용자가 정보를 제출하기 전에 대화상자를 종료하거나 닫습니다.	`CANCEL_DIALOG`	선택적으로 Chat 앱은 새 메시지로 응답하거나 사용자가 대화상자를 연 메시지 또는 카드를 업데이트할 수 있습니다.

자세한 내용은 대화형 대화상자 열기를 참고하세요.

Chat 앱 상호작용 이벤트 수신

이 섹션에서는 Chat 앱의 상호작용 이벤트를 수신하고 처리하는 방법을 설명합니다.

상호작용 이벤트를 수신하도록 Chat 앱 구성

일부 채팅 앱은 대화형이 아닙니다. 예를 들어 수신 웹훅은 발신 메시지만 보낼 수 있으며 사용자에게 응답할 수 없습니다. 대화형 Chat 앱을 빌드하는 경우 Chat 앱이 상호작용 이벤트를 수신, 처리, 응답할 수 있는 엔드포인트를 선택해야 합니다. Chat 앱 설계에 대해 자세히 알아보려면 Chat 앱 구현 아키텍처를 참고하세요.

빌드하려는 각 대화형 기능에 대해 Google Chat이 관련 상호작용 이벤트를 Chat 앱에 전송할 수 있도록 Chat API에서 구성을 업데이트해야 합니다.

Google Cloud 콘솔에서 Chat API 페이지로 이동하여 구성 페이지를 클릭합니다.

Chat API 구성 페이지로 이동

대화형 기능에서 설정을 검토하고 빌드하려는 기능에 따라 업데이트합니다.

필드	설명
기능	필수 항목입니다. Chat 앱이 사용자와 상호작용할 수 있는 방법을 결정하는 필드 집합입니다. 기본적으로 사용자는 Google Chat에서 바로 Chat 앱을 찾고 메시지를 보낼 수 있습니다. 스페이스 및 그룹 대화 참여: 사용자는 스페이스 및 그룹 대화에 Chat 앱을 추가할 수 있습니다.
연결 설정	필수 항목입니다. Chat 앱의 엔드포인트입니다. 다음 중 하나입니다. HTTP 엔드포인트 URL: 채팅 앱 구현을 호스팅하는 HTTPS 엔드포인트입니다. Apps Script: Chat 앱을 구현하는 Apps Script 프로젝트의 배포 ID입니다. Cloud Pub/Sub 주제 이름: Chat 앱이 엔드포인트로 구독하는 Pub/Sub 주제입니다. Dialogflow: Dialogflow 통합으로 Chat 앱을 등록합니다. 자세한 내용은 자연어를 이해하는 Dialogflow Google Chat 앱 빌드를 참고하세요.
명령어	선택사항입니다. Chat 앱의 슬래시 명령어 및 빠른 명령어입니다. 명령어를 사용하면 사용자가 작업을 요청하거나 Chat 앱의 특정 기능을 사용할 수 있습니다. 자세한 내용은 Google Chat 앱 명령어에 응답하기를 참고하세요.
링크 미리보기	선택사항입니다. 사용자가 링크를 보낼 때 채팅 앱에서 인식하고 추가 콘텐츠를 제공하는 URL 패턴입니다. 자세한 내용은 링크 미리보기를 참고하세요.
공개 상태	선택사항입니다. Chat 앱을 보고 설치할 수 있는 개인 최대 5명 또는 하나 이상의 Google 그룹입니다. 이 필드를 사용하여 Chat 앱을 테스트하거나 팀과 Chat 앱을 공유하세요. 자세한 내용은 대화형 기능 테스트를 참고하세요.

저장을 클릭합니다. Chat 앱 구성을 저장하면 Google Workspace 조직의 지정된 사용자가 Chat 앱을 사용할 수 있습니다.

이제 채팅 앱이 Google Chat에서 상호작용 이벤트를 수신하도록 구성되었습니다.

서비스에 대한 HTTP 호출 재시도 처리

서비스에 대한 HTTPS 요청이 실패하는 경우 (예: 제한 시간, 일시적인 네트워크 오류 또는 2xx가 아닌 HTTPS 상태 코드) Google Chat에서 몇 분 이내에 몇 번 전송을 재시도할 수 있습니다 (보장되지는 않음). 따라서 특정 상황에서 채팅 앱이 동일한 메시지를 여러 번 수신할 수 있습니다. 요청이 성공적으로 완료되었지만 잘못된 메시지 페이로드를 반환하는 경우 Google Chat은 요청을 재시도하지 않습니다.

상호작용 이벤트 처리 또는 응답

이 섹션에서는 Google Chat 앱이 상호작용 이벤트를 처리하고 응답하는 방법을 설명합니다.

Chat 앱이 Google Chat에서 상호작용 이벤트를 수신한 후 다양한 방식으로 응답할 수 있습니다. 대부분의 경우 대화형 Chat 앱은 메시지로 사용자에게 답장합니다. Google Chat 앱은 데이터 소스에서 일부 정보를 조회하거나, 상호작용 이벤트 정보를 기록하거나, 그 밖의 작업을 할 수도 있습니다. 이 처리 동작이 기본적으로 Google Chat 앱을 정의합니다.

동기식으로 응답하려면 Chat 앱이 30초 이내에 응답해야 하며 응답은 상호작용이 발생한 스페이스에 게시되어야 합니다. 그렇지 않으면 채팅 앱이 비동기적으로 응답할 수 있습니다.

각 상호작용 이벤트에 대해 채팅 앱은 이벤트의 JSON 페이로드인 요청 본문을 수신합니다. 이 정보를 사용하여 응답을 처리할 수 있습니다. 이벤트 페이로드의 예는 Chat 앱 상호작용 이벤트 유형을 참고하세요.

다음 다이어그램은 Google Chat 앱이 일반적으로 다양한 유형의 상호작용 이벤트를 처리하거나 이에 응답하는 방법을 보여줍니다.

Google Chat 앱이 상호작용 이벤트를 처리하는 방식의 아키텍처

실시간 대답

상호작용 이벤트를 사용하면 Chat 앱이 실시간으로 또는 동기식으로 응답할 수 있습니다. 동기 응답에는 인증이 필요하지 않습니다.

실시간으로 응답하려면 채팅 앱이 Message 객체를 반환해야 합니다. 스페이스에서 메시지로 답장하려면 Message 객체에 text, cardsV2, accessoryWidgets 객체가 포함될 수 있습니다. 다른 유형의 응답과 함께 사용하려면 다음 가이드를 참고하세요.

메시지로 응답하기

이 예시에서 채팅 앱은 스페이스에 추가될 때마다 문자 메시지를 만들어 전송합니다. 사용자 온보딩 권장사항에 대해 알아보려면 사용자에게 Chat 앱 소개하기를 참고하세요.

사용자가 스페이스에 채팅 앱을 추가할 때 텍스트 메시지를 보내려면 채팅 앱이 ADDED_TO_SPACE 상호작용 이벤트에 응답해야 합니다. 문자 메시지로 ADDED_TO_SPACE 상호작용 이벤트에 응답하려면 다음 코드를 사용하세요.

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar
      from Google Chat. Take a look at your schedule today by typing
      `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
      learn what else I can do, type `/help`.'
    });
  }
};

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
function onAddToSpace(event) {

  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar
    from Google Chat. Take a look at your schedule today by typing
    `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
    what else I can do, type `/help`.'
  }
}

코드 샘플은 다음 텍스트 메시지를 반환합니다.

온보딩 메시지의 예

비동기적으로 응답

Chat 앱은 30초 후에 상호작용 이벤트에 응답하거나 상호작용 이벤트가 생성된 스페이스 외부에서 작업을 실행해야 하는 경우가 있습니다. 예를 들어 채팅 앱은 장기 실행 작업을 완료한 후 사용자에게 응답해야 할 수 있습니다. 이 경우 Chat 앱은 Google Chat API를 호출하여 비동기식으로 응답할 수 있습니다.

Chat API를 사용하여 메시지를 만들려면 메시지 만들기를 참고하세요. 추가 Chat API 메서드 사용에 관한 가이드는 Chat API 개요를 참고하세요.