Google Chat 사용자로부터 정보 수집 및 처리

이 가이드에서는 Google Chat 앱이 카드 기반 인터페이스에서 양식 입력을 빌드하여 사용자로부터 정보를 수집하고 처리하는 방법을 설명합니다.

다양한 위젯이 표시된 대화상자 — **그림 1**: 연락처 정보를 수집하는 대화상자를 여는 샘플 Chat 앱

**그림 1**: 연락처 정보를 수집하는 대화상자를 여는 샘플 Chat 앱

Chat 앱은 다음과 같은 방법으로 Chat 내부 또는 외부에서 작업을 실행하기 위해 사용자에게 정보를 요청합니다.

설정을 구성합니다. 예를 들어 사용자가 알림 설정을 맞춤설정하거나 Chat 앱을 하나 이상의 스페이스에 구성하고 추가할 수 있도록 합니다.
다른 Google Workspace 애플리케이션에서 정보를 만들거나 업데이트합니다. 예를 들어 사용자가 Google Calendar 일정을 만들 수 있도록 합니다.
사용자가 다른 앱 또는 웹 서비스에서 리소스에 액세스하고 업데이트할 수 있도록 합니다. 예를 들어 Chat 앱을 사용하면 사용자가 Chat 스페이스에서 직접 지원 티켓의 상태를 업데이트할 수 있습니다.

기본 요건

Node.js

상호작용 이벤트를 수신하고 이에 응답하는 Google Chat 앱입니다. HTTP 서비스를 사용하여 대화형 Chat 앱을 만들려면 이 빠른 시작을 완료하세요.

Python

상호작용 이벤트를 수신하고 이에 응답하는 Google Chat 앱입니다. HTTP 서비스를 사용하여 대화형 Chat 앱을 만들려면 이 빠른 시작을 완료하세요.

자바

상호작용 이벤트를 수신하고 이에 응답하는 Google Chat 앱입니다. HTTP 서비스를 사용하여 대화형 Chat 앱을 만들려면 이 빠른 시작을 완료하세요.

Apps Script

상호작용 이벤트를 수신하고 이에 응답하는 Google Chat 앱입니다. Apps Script에서 대화형 Chat 앱을 만들려면 이 빠른 시작을 완료하세요.

카드를 사용하여 양식 빌드

정보를 수집하기 위해 Chat 앱은 양식과 입력을 디자인하고 이를 카드에 빌드합니다. 사용자에게 카드를 표시하기 위해 Chat 앱은 다음 Chat 인터페이스를 사용할 수 있습니다.

메시지 하나 이상의 카드가 포함된 메시지입니다.
홈페이지는 Chat 앱과의 다이렉트 메시지의 홈 탭에 표시되는 카드입니다.
대화상자는 메시지 및 홈페이지에서 새 창으로 열리는 카드입니다.

Chat 앱은 다음 위젯을 사용하여 카드를 빌드할 수 있습니다.

사용자에게 정보를 요청하는 양식 입력 위젯입니다. 선택적으로 양식 입력 위젯에 유효성 검사 를 추가하여 사용자가 정보를 올바르게 입력하고 형식을 지정하도록 할 수 있습니다. Chat 앱은 다음 양식 입력 위젯을 사용할 수 있습니다.
- 자유 형식 또는 추천 텍스트를 위한 텍스트 입력 (textInput)입니다.
- 선택 입력 (selectionInput)은 체크박스, 라디오 버튼, 드롭다운 메뉴와 같은 선택 가능한 UI 요소입니다. 선택 입력 위젯은 정적 또는 동적 데이터 소스의 항목을 채울 수도 있습니다. 예를 들어 사용자는 자신이 회원으로 속한 Chat 스페이스 목록에서 선택할 수 있습니다.
- 날짜 시간 선택기 (dateTimePicker)는 날짜 및 시간 입력을 위한 것입니다.
사용자가 카드에 입력한 값을 제출할 수 있는 버튼 위젯 입니다. 사용자가 버튼을 클릭하면 Chat 앱에서 수신한 정보를 처리할 수 있습니다.

다음 예에서는 카드가 텍스트 입력, 날짜 시간 선택기, 선택 입력을 사용하여 연락처 정보를 수집합니다.

이 연락처 양식을 사용하는 Chat 앱의 예는 다음 코드를 참고하세요.

Node.js

node/contact-form-app/index.js

GitHub에서 보기

/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": false
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": false
        }
      ]
    }
  }
];

Python

python/contact-form-app/main.py

GitHub에서 보기

# The section of the contact card that contains the form input widgets. Used in a dialog and card message.
# To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": False
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": False
        }
      ]
    }
  }
]

자바

java/contact-form-app/src/main/java/com/google/chat/contact/App.java

GitHub에서 보기

// The section of the contact card that contains the form input widgets. Used in a dialog and card message.
// To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
final static private List<GoogleAppsCardV1Widget> CONTACT_FORM_WIDGETS = List.of(
  new GoogleAppsCardV1Widget().setTextInput(new GoogleAppsCardV1TextInput()
    .setName("contactName")
    .setLabel("First and last name")
    .setType("SINGLE_LINE")),
  new GoogleAppsCardV1Widget().setDateTimePicker(new GoogleAppsCardV1DateTimePicker()
    .setName("contactBirthdate")
    .setLabel("Birthdate")
    .setType("DATE_ONLY")),
  new GoogleAppsCardV1Widget().setSelectionInput(new GoogleAppsCardV1SelectionInput()
    .setName("contactType")
    .setLabel("Contact type")
    .setType("RADIO_BUTTON")
    .setItems(List.of(
      new GoogleAppsCardV1SelectionItem()
        .setText("Work")
        .setValue("Work")
        .setSelected(false),
      new GoogleAppsCardV1SelectionItem()
        .setText("Personal")
        .setValue("Personal")
        .setSelected(false)))));

Apps Script

apps-script/contact-form-app/contactForm.gs

GitHub에서 보기

/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": false
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": false
        }
      ]
    }
  }
];

정보를 수집하는 데 사용할 수 있는 대화형 위젯의 예를 더 보려면 대화형 카드 또는 대화상자 디자인을 참고하세요.

대화형 위젯에서 데이터 수신

사용자가 버튼을 클릭할 때마다 Chat 앱은 버튼의 위치에 따라 상호작용 이벤트를 수신합니다.

버튼이 메시지 또는 대화상자에 있는 경우 Chat 앱은 상호작용에 관한 정보가 포함된 CARD_CLICKED 상호작용 이벤트를 수신합니다. 상호작용 이벤트의 페이로드에는 사용자가 입력한 값이 포함된 객체가 포함됩니다.CARD_CLICKEDcommon.formInputs

객체 common.formInputs.WIDGET_NAME에서 값을 가져올 수 있습니다. 여기서 WIDGET_NAME은 위젯에 지정한 name 필드입니다. 값은 위젯의 특정 데이터 유형으로 반환됩니다 (Inputs 객체로 표시됨).

다음은 사용자가 각 위젯에 값을 입력한 CARD_CLICKED 상호작용 이벤트의 일부를 보여줍니다.

HTTP

{
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

Apps Script

{
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "": { "stringInputs": {
      "value": ["Kai 0"]
    }}},
    "contactBirthdate": { "": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }}},
      "contactType": { "": { "stringInputs": {
      "value": ["Personal"]
    }}}
  }}
}

버튼이 홈페이지에 있는 경우 Chat 앱은 SUBMIT_FORM 상호작용 이벤트를 수신합니다. 상호작용 이벤트의 페이로드에는 사용자가 입력한 값이 포함된 commonEventObject.formInputs 객체가 포함됩니다.

객체 commonEventObject.formInputs.WIDGET_NAME에서 값을 가져올 수 있습니다. 여기서 WIDGET_NAME은 위젯에 지정한 name 필드입니다. 값은 위젯의 특정 데이터 유형으로 반환됩니다 (Inputs 객체로 표시됨).

다음은 사용자가 각 위젯에 값을 입력한 SUBMIT_FORM 상호작용 이벤트의 일부를 보여줍니다.

HTTP

{
  "type": "SUBMIT_FORM",
  "commonEventObject": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

Apps Script

{
  "type": "SUBMIT_FORM",
  "commonEventObject": { "formInputs": {
    "contactName": { "": { "stringInputs": {
      "value": ["Kai 0"]
    }}},
    "contactBirthdate": { "": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }}},
      "contactType": { "": { "stringInputs": {
      "value": ["Personal"]
    }}}
  }}
}

데이터를 수신하기 위해 Chat 앱은 상호작용 이벤트를 처리하여 사용자가 위젯에 입력한 값을 가져옵니다. 다음 표에서는 지정된 양식 입력 위젯의 값을 가져오는 방법을 보여줍니다. 각 위젯의 경우 표에는 위젯이 허용하는 데이터 유형, 상호작용 이벤트에 값이 저장되는 위치, 예시 값이 표시됩니다.

양식 입력 위젯	입력 데이터 유형	상호작용 이벤트의 입력 값	예시 값
`textInput`	`stringInputs`	`event.common.formInputs.contactName.stringInputs.value[0]`	`Kai O`
`selectionInput`	`stringInputs`	첫 번째 또는 유일한 값을 가져오려면 `event.common.formInputs.contactType.stringInputs.value[0]`	`Personal`
날짜만 허용하는 `dateTimePicker`입니다.	`dateInput`	`event.common.formInputs.contactBirthdate.dateInput.msSinceEpoch`.	`1000425600000`

데이터를 다른 카드로 전송

사용자가 카드에서 정보를 제출한 후 다음 중 하나를 실행하기 위해 추가 카드를 반환해야 할 수 있습니다.

별도의 섹션을 만들어 사용자가 더 긴 양식을 작성할 수 있도록 지원합니다.
사용자가 제출하기 전에 답변을 검토할 수 있도록 초기 카드의 정보를 미리 보고 확인할 수 있도록 합니다.
양식의 나머지 부분을 동적으로 채웁니다. 예를 들어 사용자에게 약속을 만들도록 메시지를 표시하기 위해 Chat 앱은 약속 사유를 요청하는 초기 카드를 표시한 다음 약속 유형에 따라 사용 가능한 시간을 제공하는 다른 카드를 채울 수 있습니다.

초기 카드에서 입력한 데이터를 전송하려면 위젯의 name과 사용자가 입력한 값이 포함된 actionParameters 로 button 위젯을 빌드하면 됩니다. 다음 예와 같습니다.

Node.js

node/contact-form-app/index.js

GitHub에서 보기

buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Python

python/contact-form-app/main.py

GitHub에서 보기

'buttonList': { 'buttons': [{
  'text': "Submit",
  'onClick': { 'action': {
    'function': "submitForm",
    'parameters': [{
      'key': "contactName", 'value': name }, {
      'key': "contactBirthdate", 'value': birthdate }, {
      'key': "contactType", 'value': type
    }]
  }}
}]}

자바

java/contact-form-app/src/main/java/com/google/chat/contact/App.java

GitHub에서 보기

new GoogleAppsCardV1Widget().setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
  .setText("Submit")
  .setOnClick(new GoogleAppsCardV1OnClick().setAction(new GoogleAppsCardV1Action()
    .setFunction("submitForm")
    .setParameters(List.of(
      new GoogleAppsCardV1ActionParameter().setKey("contactName").setValue(name),
      new GoogleAppsCardV1ActionParameter().setKey("contactBirthdate").setValue(birthdate),
      new GoogleAppsCardV1ActionParameter().setKey("contactType").setValue(type))))))))));

Apps Script

apps-script/contact-form-app/main.gs

GitHub에서 보기

buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

사용자가 버튼을 클릭하면 Chat 앱은 데이터를 수신할 수 있는 CARD_CLICKED 상호작용 이벤트를 수신합니다.

양식 제출에 응답

카드 메시지 또는 대화상자에서 데이터를 수신한 후 Chat 앱은 수신 확인 또는 오류 반환으로 응답합니다.

다음 예에서는 Chat 앱이 텍스트 메시지를 보내 대화상자 또는 카드 메시지에서 제출된 양식을 수신했음을 확인합니다.

Node.js

node/contact-form-app/index.js

GitHub에서 보기

const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
const errorMessage = "Don't forget to name your new contact!";
if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { actionStatus: {
      statusCode: "INVALID_ARGUMENT",
      userFacingMessage: errorMessage
    }}
  }};
}

Python

python/contact-form-app/main.py

GitHub에서 보기

contact_name = event.get('common').get('parameters')["contactName"]
# Checks to make sure the user entered a contact name.
# If no name value detected, returns an error message.
error_message = "Don't forget to name your new contact!"
if contact_name == "" and "SUBMIT_DIALOG" == event.get('dialogEventType'):
  return { 'actionResponse': {
    'type': "DIALOG",
    'dialogAction': { 'actionStatus': {
      'statusCode': "INVALID_ARGUMENT",
      'userFacingMessage': error_message
    }}
  }}

자바

java/contact-form-app/src/main/java/com/google/chat/contact/App.java

GitHub에서 보기

String contactName = event.at("/common/parameters/contactName").asText();
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
String errorMessage = "Don't forget to name your new contact!";
if (contactName.isEmpty() && event.at("/dialogEventType") != null && "SUBMIT_DIALOG".equals(event.at("/dialogEventType").asText())) {
  return new Message().setActionResponse(new ActionResponse()
    .setType("DIALOG")
    .setDialogAction(new DialogAction().setActionStatus(new ActionStatus()
      .setStatusCode("INVALID_ARGUMENT")
      .setUserFacingMessage(errorMessage))));
}

Apps Script

apps-script/contact-form-app/main.gs

GitHub에서 보기

const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
const errorMessage = "Don't forget to name your new contact!";
if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { actionStatus: {
      statusCode: "INVALID_ARGUMENT",
      userFacingMessage: errorMessage
    }}
  }};
}

대화상자를 처리하고 닫으려면 확인 메시지를 보낼지, 원래 메시지 또는 카드를 업데이트할지, 아니면 대화상자를 닫을지만 지정하는 ActionResponse 객체를 반환합니다. 단계는 대화상자 닫기를 참고하세요.

문제 해결

Google Chat 앱 또는 카드가 오류를 반환하면 Chat 인터페이스에 '문제가 발생했습니다.'라는 메시지가 표시됩니다. 또는 '요청을 처리할 수 없습니다.' 경우에 따라 Chat UI 에 오류 메시지가 표시되지 않지만 Chat 앱 또는 카드가 예기치 않은 결과를 생성합니다. 예를 들어 카드 메시지가 표시되지 않을 수 있습니다.

오류 메시지가 Chat UI에 표시되지 않더라도 오류를 해결하는 데 도움이 되는 설명 오류 메시지와 로그 데이터를 사용할 수 있습니다. Chat 앱의 오류 로깅이 사용 설정되어 있으면 오류를 보고 디버깅하고 해결하는 데 도움이 필요하면 Google Chat 오류 문제 해결 및 해결을 참고하세요.

연락처 관리자 샘플을 봅니다. 이 샘플은 사용자에게 카드 메시지 및 대화상자에서 연락처 양식을 작성하도록 메시지를 표시하는 Chat 앱입니다.
대화형 대화상자 열기

Google Chat 사용자로부터 정보 수집 및 처리 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

기본 요건

Node.js

Python

자바

Apps Script

카드를 사용하여 양식 빌드

Node.js

Python

자바

Apps Script

대화형 위젯에서 데이터 수신

HTTP

Apps Script

HTTP

Apps Script

데이터를 다른 카드로 전송

Node.js

Python

자바

Apps Script

양식 제출에 응답

Node.js

Python

자바

Apps Script

문제 해결

관련 주제

Google Chat 사용자로부터 정보 수집 및 처리