대화형 대화상자 열기

이 페이지에서는 Google Chat 앱이 대화상자를 열어 사용자 인터페이스 (UI)를 표시하고 사용자에게 응답하는 방법을 설명합니다.

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

대화상자는 Chat 스페이스 또는 메시지에서 열리는 창 기반 카드 기반 인터페이스입니다. 대화상자와 그 내용은 이를 연 사용자에게만 표시됩니다.

Chat 앱은 대화상자를 사용하여 여러 단계 양식을 비롯한 Chat 사용자로부터 정보를 요청하고 수집할 수 있습니다. 양식 입력 작성에 관한 자세한 내용은 사용자로부터 정보 수집 및 처리를 참고하세요.

기본 요건

Node.js

Google Chat을 확장하는 Google Workspace 부가기능입니다. 빌드하려면 HTTP 빠른 시작을 완료하세요.

참고: 이 가이드의 코드 샘플은 Node.js용 Google Cloud 함수로 실행되도록 작성되었습니다.

Apps Script

Google Chat을 확장하는 Google Workspace 부가기능입니다. 빌드하려면 Apps Script 빠른 시작을 완료하세요.

대화상자 열기

그림 1: 연락처 정보를 수집하기 위해 대화상자를 여는 Chat 앱

이 섹션에서는 다음을 수행하여 대화에 응답하고 대화상자를 설정하는 방법을 설명합니다.

1. 사용자 상호작용에서 대화상자 요청을 트리거합니다.
2. 대화상자를 반환하고 열어 요청을 처리합니다.
3. 사용자가 정보를 제출하면 대화상자를 닫거나 다른 대화상자를 반환하여 제출을 처리합니다.

대화 요청 트리거

Chat 앱은 슬래시 명령어 또는 카드의 메시지에서 버튼을 클릭하는 등 사용자 상호작용에 응답하기 위해만 대화상자를 열 수 있습니다.

대화상자로 사용자에게 응답하려면 Chat 앱에서 다음과 같이 대화상자 요청을 트리거하는 상호작용을 빌드해야 합니다.

• 슬래시 명령어에 응답합니다. 슬래시 명령어에서 요청을 트리거하려면 명령어를 구성할 때 대화상자를 엽니다 체크박스를 선택해야 합니다.
• 메시지에서 카드의 일부 또는 메시지 하단에 있는 버튼 클릭에 응답합니다. 메시지의 버튼에서 요청을 트리거하려면 interaction를 OPEN_DIALOG로 설정하여 버튼의 onClick 작업을 구성합니다.

그림 2: Chat 앱에서 사용자에게 /addContact 슬래시 명령어를 사용하라는 메시지를 전송합니다.
메시지에는 사용자가 클릭하여 명령어를 트리거할 수 있는 버튼도 포함되어 있습니다.

다음 JSON은 카드 메시지의 버튼에서 대화 요청을 트리거하는 방법을 보여줍니다. 대화상자를 열려면 버튼의 onClick.action.interaction 필드를 OPEN_DIALOG로 설정합니다.

{
  "buttonList": { "buttons": [{
    "text": "BUTTON_TEXT",
    "onClick": { "action": {
      "function": "ACTION_FUNCTION",
      "interaction": "OPEN_DIALOG"
    }}
  }]}
}

여기서 BUTTON_TEXT는 버튼에 표시되는 텍스트이고 ACTION_FUNCTION는 초기 대화상자를 열기 위해 실행되는 함수입니다.

초기 대화상자 열기

사용자가 대화 요청을 트리거하면 Chat 앱은 dialogEventType 객체를 REQUEST_DIALOG로 지정하는 페이로드가 포함된 이벤트 객체를 수신합니다.

대화상자를 열려면 Chat 앱에서 탐색 pushCard이 포함된 RenderActions 객체를 반환하여 요청에 응답하여 카드를 표시할 수 있습니다. 카드에는 하나 이상의 sections[] 위젯을 비롯한 모든 사용자 인터페이스 (UI) 요소가 포함되어야 합니다. 사용자로부터 정보를 수집하려면 양식 입력 위젯과 버튼 위젯을 지정하면 됩니다. 양식 입력란 설계 방법에 관한 자세한 내용은 사용자로부터 정보 수집 및 처리를 참고하세요.

다음 JSON은 Chat 앱이 대화상자를 여는 응답을 반환하는 방법을 보여줍니다.

{
  "action": { "navigations": [{ "pushCard": { "sections": [{ "widgets": [{
    WIDGETS,
    { "buttonList": { "buttons": [{
      "text": "BUTTON_TEXT",
      "onClick": {
        "action": { "function": "ACTION_FUNCTION" }
      }
    }]}}
  }]}]}}]}
}

여기서 BUTTON_TEXT는 버튼에 표시되는 텍스트 (예: Next 또는 Submit)이고, WIDGETS는 하나 이상의 양식 입력 위젯을 나타내며, ACTION_FUNCTION는 사용자가 버튼을 클릭할 때 실행되는 작업의 콜백 함수입니다.

대화상자 제출 처리

사용자가 대화상자를 제출하는 버튼을 클릭하면 Chat 앱은 ButtonClickedPayload 객체가 포함된 이벤트 객체를 수신합니다. 페이로드에서 dialogEventType는 SUBMIT_DIALOG로 설정됩니다.

Chat 앱은 다음 중 하나를 실행하여 이벤트 객체를 처리해야 합니다.

• 다른 대화상자를 반환하여 다른 카드 또는 양식을 채웁니다.
• 사용자가 제출한 데이터의 유효성을 검사한 후 대화상자를 닫고 원하는 경우 확인 메시지를 보냅니다.

선택사항: 다른 대화상자 반환

사용자가 첫 번째 대화상자를 제출한 후 채팅 앱은 사용자가 제출하기 전에 정보를 검토하거나, 여러 단계의 양식을 작성하거나, 양식 콘텐츠를 동적으로 채우는 데 도움이 되는 대화상자를 하나 이상 추가로 반환할 수 있습니다.

사용자가 입력한 데이터를 처리하기 위해 Chat 앱은 이벤트의 commonEventObject.formInputs 객체에서 데이터를 처리합니다. 입력 위젯에서 값을 검색하는 방법에 관한 자세한 내용은 사용자로부터 정보 수집 및 처리를 참고하세요.

사용자가 초기 대화상자에서 입력한 데이터를 추적하려면 다음 대화상자를 여는 버튼에 매개변수를 추가해야 합니다. 자세한 내용은 다른 카드로 데이터 전송하기를 참고하세요.

이 예시에서 Chat 앱은 제출하기 전에 확인을 위한 두 번째 대화상자로 연결되는 첫 번째 대화상자를 엽니다.

Node.js

이 샘플은 Google Cloud 함수로 실행됩니다.

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(req.body));
  // Handle button clicks
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openInitialDialog":
            return res.send(openInitialDialog(req.body));
        case "openConfirmationDialog":
            return res.send(openConfirmationDialog(req.body));
        case "submitDialog":
            return res.send(submitDialog(req.body));
    }
  }
};

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} response that handles dialogs.
 */
function handleMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openInitialDialog" }],
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openConfirmationDialog" }]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{
          key: "actionName", value: "submitDialog" }, {
          // Pass input values as parameters for last dialog step (submission)
          key: "contactName", value: name
        }]
      }}
    }]}}]
  }]}}]}};
}

Apps Script

이 예에서는 카드 JSON을 반환하여 카드 메시지를 전송합니다. Apps Script 카드 서비스를 사용할 수도 있습니다.

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} response that handles dialogs.
 */
function onMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        function: "openInitialDialog",
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: { function : "openConfirmationDialog" }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [{ key: "contactName", value: name }]
      }}
    }]}}]
  }]}}]}};
}

여기서 WIDGETS는 다른 양식 입력 위젯을 나타냅니다.

대화상자 닫기

사용자가 대화상자의 제출 버튼을 클릭하면 Chat 앱이 연결된 작업을 실행하고 buttonClickedPayload가 다음으로 설정된 이벤트 객체를 제공합니다.

• isDialogEvent은 true입니다.
• dialogEventType은 SUBMIT_DIALOG입니다.

Chat 앱은 EndNavigation이 CLOSE_DIALOG로 설정된 RenderActions 객체를 반환해야 합니다.

선택사항: 알림 표시

대화상자를 닫을 때 텍스트 알림을 표시할 수도 있습니다.

알림을 표시하려면 notification 필드가 설정된 RenderActions 객체를 반환합니다.

다음 예에서는 매개변수가 유효한지 확인하고 결과에 따라 텍스트 알림과 함께 대화상자를 닫습니다.

Node.js

이 샘플은 Google Cloud 함수로 실행됩니다.

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

Apps Script

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

대화상자 간에 매개변수를 전달하는 방법에 관한 자세한 내용은 다른 카드로 데이터 전송을 참고하세요.

선택사항: 확인 메시지 보내기

대화상자를 닫을 때 새 메시지를 보내거나 기존 메시지를 업데이트할 수도 있습니다.

새 메시지를 보내려면 새 메시지로 설정된 CreateMessageAction 필드가 있는 DataActions 객체를 반환합니다. 예를 들어 대화상자를 닫고 문자 메시지를 보내려면 다음을 반환합니다.

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {
  "text": "Your information has been submitted."
}}}}}

사용자가 대화상자를 제출한 후 메시지를 업데이트하려면 다음 작업 중 하나가 포함된 DataActions 객체를 반환합니다.

• UpdateMessageAction: 사용자가 대화상자를 요청한 메시지와 같이 Chat 앱에서 전송한 메시지를 업데이트합니다.
• UpdateInlinePreviewAction: 링크 미리보기에서 카드를 업데이트합니다.

문제 해결

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

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