Google Chat에서 슬래시 명령어에 응답하기

이 페이지에서는 슬래시 명령어에 응답하도록 Google Chat 앱을 구성하는 방법을 설명합니다.

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

슬래시 명령어는 사용자가 Chat 앱을 호출하고 상호작용하는 일반적인 방법입니다. 슬래시 명령어는 사용자가 Chat 앱의 주요 기능을 찾고 사용하는 데도 도움이 됩니다. 슬래시 명령어를 설정해야 하는지 결정하고 사용자 상호작용을 설계하는 방법을 알아보려면 Chat API 문서의 모든 사용자 여정 정의를 참고하세요.

사용자가 슬래시 명령어를 사용하는 방법

슬래시 명령어를 사용하려면 사용자가 슬래시 (/)를 입력한 다음 /about와 같은 짧은 텍스트 명령어를 입력하여 Chat 앱에 관한 정보를 가져옵니다. 사용자는 Google Chat에 슬래시를 입력하여 사용 가능한 슬래시 명령어를 확인할 수 있습니다. 그러면 Chat 앱에서 사용할 수 있는 명령어가 나열된 창이 표시됩니다.

슬래시 명령어 창
그림 1: 사용자가 Google Chat에 슬래시를 입력할 때 표시되는 창

사용자가 슬래시 명령어가 포함된 메시지를 보내면 이 메시지는 사용자와 Chat 앱에만 표시됩니다. 여러 사용자가 있는 스페이스에 Chat 앱을 추가하도록 구성한 경우 사용자와 Chat 앱 간의 상호작용을 비공개로 유지하기 위해 슬래시 명령어에 비공개로 응답하는 것이 좋습니다.

예를 들어 스페이스에서 발견한 Chat 앱에 관해 알아보려면 사용자는 /about 또는 /help와 같은 명령어를 사용할 수 있습니다. 스페이스의 다른 모든 사용자에게 알림이 전송되지 않도록 하려면 Chat 앱이 Chat 앱을 사용하고 지원을 받는 방법에 관한 정보를 비공개로 응답할 수 있습니다.

기본 요건

Node.js

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

Apps Script

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

슬래시 명령어 설정

이 섹션에서는 다음 단계를 완료하여 슬래시 명령어를 설정하는 방법을 설명합니다.

  1. 슬래시 명령어의 이름을 만듭니다.
  2. Google Chat API에서 슬래시 명령어를 구성합니다.

슬래시 명령어 이름 지정

슬래시 명령어의 이름은 사용자가 Chat 메시지에 입력하여 Chat 앱을 호출하는 명령어입니다. 이름 아래에는 명령어 사용 방법을 사용자에게 자세히 안내하는 간단한 설명도 표시됩니다.

슬래시 명령어 이름 및 설명
그림 2: 슬래시 명령어의 이름 및 설명

슬래시 명령어의 이름과 설명을 선택할 때는 다음 권장사항을 고려하세요.

  • 슬래시 명령어의 이름을 지정하려면 다음 단계를 따르세요.

    • 명령어를 사용자에게 명확하고 간단하게 전달하려면 짧고 설명적이고 실행 가능한 단어 또는 문구를 사용하세요. 예를 들어 /createAReminder 대신 /remindMe을 사용합니다.
    • 명령어에 두 개 이상의 단어가 포함된 경우 첫 번째 단어는 모두 소문자로 사용하고 추가 단어의 첫 글자는 대문자로 사용하여 사용자가 명령어를 읽을 수 있도록 지원합니다. 예를 들어 /updatecontact 대신 /updateContact를 사용합니다.
    • 명령어에 고유한 이름을 사용할지 아니면 일반적인 이름을 사용할지 고려하세요. 명령어가 일반적인 상호작용이나 기능을 설명하는 경우 사용자가 인식하고 예상하는 일반적인 이름(예: /settings 또는 /feedback)을 사용할 수 있습니다. 그렇지 않은 경우 고유한 명령어 이름을 사용하세요. 다른 Chat 앱에서 명령어 이름이 동일하면 사용자가 유사한 명령어를 필터링하여 내 명령어를 찾아야 하기 때문입니다.
  • 슬래시 명령어를 설명하려면 다음 단계를 따르세요.

    • 사용자가 명령어를 호출할 때 무엇을 기대할 수 있는지 알 수 있도록 설명을 짧고 명확하게 유지합니다.
    • 명령어에 형식 지정 요구사항이 있는지 사용자에게 알립니다. 예를 들어 인수 텍스트가 필요한 /remindMe 명령어를 만드는 경우 설명을 Remind me to do [something] at [time]과 같이 설정합니다.
    • Chat 앱이 스페이스의 모든 사용자에게 답장하는지 또는 명령어를 호출한 사용자에게 비공개로 답장하는지 사용자에게 알립니다. 예를 들어 슬래시 명령어 /aboutLearn about this app (Only visible to you)으로 설명할 수 있습니다.

Google Chat API에서 슬래시 명령어 구성

슬래시 명령어를 만들려면 Google Chat API용 Chat 앱 구성에서 명령어에 관한 정보를 지정해야 합니다.

Google Chat API에서 슬래시 명령어를 구성하려면 다음 단계를 완료하세요.

  1. Google Cloud 콘솔에서 메뉴 > API 및 서비스 > 사용 설정된 API 및 서비스 > Google Chat API를 클릭합니다.

    Google Chat API 페이지로 이동

  2. 구성을 클릭합니다.

  3. 고급 설정에서 트리거로 이동하여 MESSAGE 필드에 HTTP 엔드포인트 또는 Apps Script 함수와 같은 트리거가 포함되어 있는지 확인합니다. 다음 섹션에서 이 트리거를 사용하여 슬래시 명령어에 응답해야 합니다.

  4. 슬래시 명령어에서 슬래시 명령어 추가를 클릭합니다.

  5. 명령어의 이름, 명령어 ID, 설명을 입력합니다.

    1. 이름: 명령어의 표시 이름이며 사용자가 앱을 호출하기 위해 입력하는 이름입니다. 슬래시로 시작해야 하며 텍스트만 포함할 수 있으며 최대 50자(영문 기준)까지 가능합니다.
    2. 설명: 명령어 사용 및 형식 지정 방법을 설명하는 텍스트입니다. 설명은 최대 50자(영문 기준)까지 입력할 수 있습니다.
    3. 명령어 ID: Chat 앱에서 슬래시 명령어를 인식하고 응답을 반환하는 데 사용하는 1~1,000 사이의 숫자입니다.
  6. 선택사항: 채팅 앱이 대화상자로 명령어에 응답하도록 하려면 대화상자 열기 체크박스를 선택합니다.

  7. 저장을 클릭합니다.

이제 Chat 앱에 슬래시 명령어가 구성되었습니다.

슬래시 명령어에 응답

사용자가 Chat 메시지를 만들면 Chat 앱은 메시지에 관한 정보가 포함된 이벤트 객체를 수신합니다. 이벤트 객체에는 적절한 응답을 반환할 수 있도록 메시지에 사용된 명령어에 관한 세부정보 (명령어 ID 포함)가 포함된 페이로드가 포함됩니다.

슬래시 명령어에 응답하려면 채팅 앱에서 슬래시 명령어 메타데이터가 포함된 이벤트 객체를 처리할 수 있도록 메시지 트리거를 구현해야 합니다.

Cymbal Labs Chat 앱을 위한 비공개 메시지입니다. 이 메시지에는 Chat 앱이 Cymbal Labs에서 만들었으며 문서 링크와 지원팀에 문의할 수 있는 링크가 공유되어 있습니다.
Chat 앱이 슬래시 명령어 /help에 비공개로 응답하여 지원을 받는 방법을 설명합니다.

다음 코드는 /about 슬래시 명령어에 텍스트 메시지로 답장하는 Chat 앱의 예를 보여줍니다. 채팅 앱은 슬래시 명령어에 응답하기 위해 Message 트리거의 이벤트 객체를 처리합니다. 이벤트 객체의 페이로드에 슬래시 명령어 ID가 포함된 경우 Chat 앱은 createMessageAction 객체와 함께 작업 DataActions를 반환합니다.

Node.js

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Google Cloud Function that responds to messages sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.avatarApp = function avatarApp(req, res) {
    if (req.method === 'GET' || !req.body.chat) {
        return res.send('Hello! This function is meant to be used ' +
            'in a Google Chat Space.');
    }

    // Stores the Google Chat event as a variable.
    const chatMessage = req.body.chat.messagePayload.message;

    if (chatMessage.slashCommand) {
        // Executes the slash command logic based on its ID.
        // Slash command IDs are set in the Google Chat API configuration.
        switch (chatMessage.slashCommand.commandId) {
            case ABOUT_COMMAND_ID:
                return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                    text: 'The Avatar app replies to Google Chat messages.'
                }}}}});
        }
    }

    // Replies with the sender's avatar in a card otherwise.
    const displayName = chatMessage.sender.displayName;
    const avatarUrl = chatMessage.sender.avatarUrl;
    res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'Here\'s your avatar',
        cardsV2: [{
            cardId: 'avatarCard',
            card: {
                name: 'Avatar Card',
                header: {
                    title: `Hello ${displayName}!`,
                },
                sections: [{
                    widgets: [{
                        textParagraph: { text: 'Your avatar picture: ' }
                    }, {
                        image: { imageUrl: avatarUrl }
                    }]
                }]
            }
        }]
    }}}}});
};

Apps Script

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
    // Stores the Google Chat event as a variable.
    const chatMessage = event.chat.messagePayload.message;

    if (chatMessage.slashCommand) {
        // Executes the slash command logic based on its ID.
        // Slash command IDs are set in the Google Chat API configuration.
        switch (chatMessage.slashCommand.commandId) {
            case ABOUT_COMMAND_ID:
                return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                    text: 'The Avatar app replies to Google Chat messages.'
                }}}}};
        }
    }

    // Replies with the sender's avatar in a card otherwise.
    const displayName = chatMessage.sender.displayName;
    const avatarUrl = chatMessage.sender.avatarUrl;
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'Here\'s your avatar',
        cardsV2: [{
            cardId: 'avatarCard',
            card: {
                name: 'Avatar Card',
                header: {
                    title: `Hello ${displayName}!`,
                },
                sections: [{
                    widgets: [{
                        textParagraph: { text: 'Your avatar picture: ' }
                    }, {
                        image: { imageUrl: avatarUrl }
                    }]
                }]
            }
        }]
    }}}}};
}

이 코드 샘플을 사용하려면 ABOUT_COMMAND_IDChat API에서 슬래시 명령어를 구성할 때 지정한 명령어 ID로 바꿉니다.