Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

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

이 페이지에서는 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 유형으로 표시됩니다. 채팅 앱은 이 이벤트를 사용하여 상호작용을 처리하고 선택적으로 메시지로 응답할 수 있습니다.

각 사용자 상호작용 유형에 대해 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`	Chat 앱은 스페이스에 구성된 수신 알림을 삭제하고 (예: 웹훅 삭제) 내부 저장소를 정리합니다.
사용자가 채팅 앱 메시지, 대화상자 또는 홈페이지의 카드에 있는 버튼을 클릭합니다.	`CARD_CLICKED`	Chat 앱은 사용자가 제출한 데이터를 처리하고 저장하거나 다른 카드를 반환합니다.
사용자가 1:1 메시지에서 홈 탭을 클릭하여 Chat 앱의 홈페이지를 엽니다.	`APP_HOME`	채팅 앱이 홈페이지에서 정적 또는 대화형 카드를 반환합니다.
사용자가 Chat 앱의 홈페이지에서 양식을 제출합니다.	`SUBMIT_FORM`	Chat 앱은 사용자가 제출한 데이터를 처리하고 저장하거나 다른 카드를 반환합니다.
사용자가 빠른 명령어를 사용하여 명령어를 호출합니다.	`APP_COMMAND`	채팅 앱은 호출된 명령어를 기반으로 응답합니다. 예를 들어 Chat 앱은 About 명령어에 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: 채팅 앱을 구현하는 Apps Script 프로젝트의 배포 ID입니다. Cloud Pub/Sub 주제 이름: Chat 앱이 엔드포인트로 구독하는 Pub/Sub 주제입니다. Dialogflow: Chat 앱을 Dialogflow 통합에 등록합니다. 자세한 내용은 자연어를 이해하는 Dialogflow Google Chat 앱 빌드를 참고하세요.
명령어	선택사항입니다. Chat 앱의 슬래시 명령어 및 빠른 명령어입니다. 명령어를 사용하면 사용자가 작업을 요청하거나 Chat 앱의 특정 기능을 사용할 수 있습니다. 자세한 내용은 Google Chat 앱 명령어에 응답하기를 참고하세요.
시작 프롬프트	선택사항입니다. ( 개발자 프리뷰) 사용자가 Chat 앱과의 빈 1:1 채팅 메시지를 열 때 표시되는 최대 3개의 제로 스테이트 프롬프트입니다. 프롬프트는 작성 영역에 텍스트를 채우거나 (다국어 현지화 지원) 슬래시/빠른 명령어를 직접 트리거할 수 있습니다. 자세한 내용은 시작 프롬프트 구성을 참고하세요.
링크 미리보기	선택사항입니다. 사용자가 링크를 보낼 때 채팅 앱에서 인식하고 추가 콘텐츠를 제공하는 URL 패턴입니다. 자세한 내용은 링크 미리보기를 참고하세요.
공개 상태	선택사항입니다. Chat 앱을 보고 설치할 수 있는 개인 최대 5명 또는 하나 이상의 Google 그룹입니다. 이 필드를 사용하여 Chat 앱을 테스트하거나 팀과 Chat 앱을 공유합니다. 자세한 내용은 대화형 기능 테스트를 참고하세요.

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

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

시작 프롬프트 구성

시작 프롬프트는 사용자가 앱과의 빈 1:1 채팅 메시지를 열 때 채팅 앱의 기능을 발견하는 데 도움이 됩니다. 최대 3개의 시작 프롬프트를 구성할 수 있습니다.

시작 프롬프트를 추가하고 구성하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 Chat API 구성 페이지로 이동합니다.

Chat API 구성 페이지로 이동
인터랙티브 기능에서 시작 프롬프트를 찾아 프롬프트 추가를 클릭합니다.
순위 (1~3) 필드에 1~3 사이의 숫자를 입력하여 표시 순서를 지정합니다.
유형 선택에서 프롬프트의 동작 방식을 선택합니다.
- 텍스트 프롬프트: 사용자가 프롬프트 칩을 클릭하면 미리 정의된 텍스트로 작성 창을 채웁니다.
- 명령 프롬프트: 클릭하면 등록된 슬래시 명령어 또는 빠른 명령어를 실행합니다. 추가 인수가 필요한 명령어는 선택할 수 없습니다.
유형 선택에 따라 프롬프트를 구성합니다.
- 텍스트 프롬프트를 선택한 경우:
  1. 제목에 칩에 표시되는 프롬프트 제목을 입력합니다 (최대 30자).
  2. 프롬프트 텍스트에 작성 창에 입력된 텍스트를 입력합니다 (최대 60자).
  3. 선택사항: 다른 언어를 사용하는 사용자를 위해 현지화된 제목과 텍스트를 추가합니다.
  4. 현지화된 프롬프트에서 언어 추가를 클릭합니다.
  5. 언어에서 드롭다운을 통해 지원되는 언어를 선택합니다.
  6. 현지화된 제목에 현지화된 제목을 입력합니다 (영문 기준 최대 30자).
  7. 현지화된 프롬프트 텍스트에 현지화된 프롬프트 텍스트를 입력합니다 (최대 60자).
  8. 필요에 따라 언어를 추가하려면 이 단계를 반복합니다.
- 명령 프롬프트를 선택한 경우:
  1. 슬래시 명령어 / 빠른 명령어에서 드롭다운에서 명령어를 선택합니다.
완료를 클릭한 다음 페이지 하단의 저장을 클릭합니다.

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

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

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

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

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

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

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

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

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

실시간 대답

상호작용 이벤트를 사용하면 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.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // 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`.'
    });
  }
};

Python

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      '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`.'
    })
  return json.jsonify({})

자바

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return new Message().setText(
          "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`.");
      default:
        return new Message();
    }
  }
}

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.
 */
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 개요를 참고하세요.