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. 省略可: Chat アプリがコマンドにダイアログで応答する場合は、[ダイアログを開く] チェックボックスをオンにします。

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

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

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

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

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

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

次のコードは、/about スラッシュ コマンドにテキスト メッセージで返信する Chat アプリの例を示しています。スラッシュ コマンドに応答するため、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_ID を、Chat API でスラッシュ コマンドを構成したときに指定したコマンド ID に置き換えてください。