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. [詳細設定] の [トリガー] に移動し、[アプリ コマンド] フィールドに HTTP エンドポイントや Apps Script 関数などのトリガーが含まれていることを確認します。次のセクションでスラッシュ コマンドに応答するには、このトリガーを使用する必要があります。

  4. [コマンド] で [コマンドを追加] をクリックします。

  5. コマンド ID、コマンドタイプ、スラッシュ コマンド名、名前、コマンドの説明を入力します。

    1. コマンド ID: Chat アプリがスラッシュ コマンドを認識してレスポンスを返すために使用する 1 ~ 1,000 の数字。
    2. コマンドタイプ: [スラッシュ コマンド] を選択します。
    3. スラッシュ コマンド名: コマンドの表示名で、ユーザーがアプリを起動するために入力するものです。先頭はスラッシュにする必要があります。テキストのみを含め、最大 50 文字にすることができます。
    4. 名前: コマンドのわかりやすい名前。名前は 50 文字までで、特殊文字を含めることができます。
      • 短く、説明的で、実行可能な単語やフレーズを使用して、コマンドをユーザーに明確に伝えます。たとえば、連絡先レコードを変更するコマンドには Update contact を使用します。
    5. 説明: コマンドの使用方法と形式を説明するテキスト。説明の最大文字数は 50 文字です。
  6. 省略可: Chat アプリがコマンドにダイアログで応答する場合は、[ダイアログを開く] チェックボックスをオンにします。

  7. [保存] をクリックします。

これで、Chat アプリ用にスラッシュ コマンドが構成されました。

スラッシュ コマンドに応答する

ユーザーが Chat メッセージを作成すると、Chat アプリはメッセージに関する情報を含むイベント オブジェクトを受信します。イベント オブジェクトには、メッセージで使用されたコマンドに関する詳細(コマンド ID を含む)を含む AppCommand ペイロードが含まれるため、適切なレスポンスを返すことができます。

スラッシュ コマンドに応答するには、アプリコマンドトリガーを実装して、Chat アプリがアプリコマンド メタデータを含むイベント オブジェクトを処理できるようにする必要があります。

Cymbal Labs の Chat アプリの非公開メッセージ。このメッセージには、Chat アプリが Cymbal Labs によって作成されたこと、ドキュメントへのリンク、サポートチームへの連絡先のリンクが記載されています。
Chat アプリは、スラッシュ コマンド /help に非公開で応答し、サポートを受ける方法を説明します。

次のコードは、/about スラッシュ コマンドにテキスト メッセージで返信する Chat アプリの例を示しています。スラッシュ コマンドに応答するため、Chat アプリは アプリコマンド トリガーのイベント オブジェクトを処理します。イベント オブジェクトのペイロードにスラッシュ コマンド 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 events 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 chatEvent = req.body.chat;

    // Handles APP_COMMAND events
    if (chatEvent.appCommandPayload) {

        // Stores the Google Chat app command metadata as a variable.
        const appCommandMetadata = chatEvent.appCommandPayload.appCommandMetadata;

        if (appCommandMetadata.appCommandType === "SLASH_COMMAND") {
            // Executes the slash command logic based on its ID.
            // Slash command IDs are set in the Google Chat API configuration.
            switch (appCommandMetadata.appCommandId) {
                case ABOUT_COMMAND_ID:
                    return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                        text: 'The Avatar app replies to Google Chat messages.'
                    }}}}});
            }
        }
    // Handles MESSAGE events
    } else if (chatEvent.messagePayload) {

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

        // 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;

    // 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 }
                    }]
                }]
            }
        }]
    }}}}};
}

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {

    // Stores the Google Chat app command metadata as a variable.
    const appCommandMetadata = event.chat.appCommandPayload.appCommandMetadata;

    if (appCommandMetadata.appCommandType == "SLASH_COMMAND") {

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

このコードサンプルを使用するには、ABOUT_COMMAND_ID を、Chat API でスラッシュ コマンドを構成したときに指定したコマンド ID に置き換えてください。