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

사용자 상호작용을 수신하고 이에 응답

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

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

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

Google Workspace 부가기능으로 대화형 Chat 앱 빌드

Chat 사용자와 상호작용하는 Chat 앱을 빌드하려면 Chat을 확장하는 Google Workspace 부가기능을 빌드하면 됩니다. Chat 앱은 Chat API에서 상호작용 이벤트를 수신하는 대신 부가기능 이벤트 객체를 수신하고 응답합니다. 자세한 내용은 Google Workspace 부가기능 문서의 Google Chat 확장을 참고하세요.

기본 요건

대화형 기능이 사용 설정된 Google Chat 앱 대화형 Chat 앱을 만들려면 사용하려는 앱 아키텍처에 따라 다음 빠른 시작 중 하나를 완료하세요.

상호작용 이벤트 유형

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

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

Google Chat은 사용자 상호작용 유형별로 서로 다른 유형의 상호작용 이벤트를 전송하므로 Chat 앱에서 각 이벤트 유형을 적절하게 처리할 수 있습니다. 상호작용 이벤트 유형은 eventType 객체를 사용하여 나타냅니다.

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

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

다음 표에는 일반적인 사용자 상호작용, Chat 앱에서 수신하는 상호작용 이벤트 유형, Chat 앱에서 일반적으로 응답하는 방식이 나와 있습니다.

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

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

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

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

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

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

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

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

Chat 앱 상호작용 이벤트 수신

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

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

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

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

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

Chat API 구성 페이지로 이동

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

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

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

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

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

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

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

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

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

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

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

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

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

실시간 대답

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

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

메시지로 응답하기

이 예시에서는 Chat 앱이 스페이스에 추가될 때마다 문자 메시지를 생성하고 전송합니다. 사용자 온보딩 권장사항을 알아보려면 사용자에게 Chat 앱 소개하기를 참고하세요.

사용자가 Chat 앱을 스페이스에 추가할 때 텍스트 메시지를 보내려면 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 개요를 참고하세요.