このページは Cloud Translation API によって翻訳されました。

Google Chat アプリのコマンドに応答する

このページでは、Google Chat アプリとしてコマンドを設定して応答する方法について説明します。

コマンドは、ユーザーが Chat アプリの主要な機能を探して使用できるようにします。コマンドのコンテンツを表示できるのは Chat アプリのみです。たとえば、ユーザーがスラッシュコマンドを使用してメッセージを送信した場合、そのメッセージはユーザーと Chat アプリにのみ表示されます。

コマンドを作成するかどうかを判断し、ユーザーインタラクションを設計する方法については、すべてのユーザージャーニーを定義するをご覧ください。

Chat アプリコマンドの種類

Chat アプリのコマンドは、スラッシュコマンドまたはクイックコマンドとして作成できます。各タイプのコマンドを見つけて使用するには、次の操作を行います。

スラッシュコマンド: スラッシュ（/）と、事前定義されたテキスト（/about など）を入力して、コマンドをメッセージとして送信します。チャットアプリでは、スラッシュコマンドに引数テキストを指定することもできます。たとえば、スラッシュコマンド /search では、検索クエリに使用する引数テキストが必要になる場合があります。
クイックコマンド: ユーザーは、Chat メッセージの返信欄からメニューを開いてコマンドを使用します。コマンドを使用するには、[追加] をクリックし、メニューからコマンドを選択します。

次の画像は、ユーザーがスラッシュコマンドとクイックコマンドのメニューを表示する方法を示しています。

図 1: ユーザーは、返信欄にスラッシュ / とコマンド名を入力して、スラッシュコマンドを見つけて使用します。
図 2. ユーザーは、Chat メッセージの返信欄にあるメニューからクイックコマンドを見つけて使用します。

前提条件

HTTP

Google Chat を拡張する Google Workspace アドオン。ビルドするには、HTTP クイックスタートを完了します。

Apps Script

Google Chat を拡張する Google Workspace アドオン。作成するには、Apps Script のクイックスタートを完了します。

コマンドを設定する

このセクションでは、次の手順でコマンドを設定する方法について説明します。

コマンドに名前と説明を作成します。
Google Cloud コンソールでコマンドを構成します。

コマンドの名前と説明を入力します

コマンドの名前は、ユーザーが Chat アプリを起動するために入力または選択するものです。名前の下に簡単な説明も表示され、コマンドの使用方法についてユーザーに提示します。

コマンドの名前と説明を選択する際は、次の推奨事項を考慮してください。

コマンドに名前を付けるには:

短く、説明的で、実行可能な単語やフレーズを使用して、ユーザーにコマンドを明確に伝えます。たとえば、名前 Create a reminder の代わりに Remind me を使用します。
コマンドに一意の名前または共通の名前を使用することを検討してください。コマンドが一般的な操作や機能を表す場合は、ユーザーが認識し期待する一般的な名前（Settings や Feedback など）を使用できます。それ以外の場合は、一意のコマンド名を使用することをおすすめします。コマンド名が他の Chat アプリと同じである場合、ユーザーは類似のコマンドをフィルタしてコマンドを見つけて使用する必要があります。

コマンドの説明を取得するには:

コマンドを使用する際にユーザーが期待できる内容を把握できるように、説明は簡潔でわかりやすいものにします。
コマンドに書式設定の要件がある場合は、ユーザーに伝えます。たとえば、引数テキストを必要とするスラッシュコマンドを作成する場合は、説明を Remind me to do [something] at [time] などに設定します。
Chat アプリがスペース内の全員に返信するか、コマンドを呼び出したユーザーに非公開で返信するかをユーザーに伝えます。たとえば、クイックコマンド About は Learn about this app (Only visible to you) と記述できます。

Google Cloud コンソールでコマンドを構成する

スラッシュコマンドまたはクイックコマンドを作成するには、Google Chat API 用に Chat アプリの構成でコマンドに関する情報を指定します。

Google Chat API でコマンドを構成するには、次の手順を完了します。 o Google Chat API でスラッシュコマンドを構成するには、次の手順を完了します。

Google Cloud コンソールで、メニュー > [API とサービス] > [有効な API とサービス] > [Google Chat API] をクリックします。

Google Chat API ページに移動
[構成] をクリックします。
[接続設定] で [トリガー] に移動し、エンドポイントの詳細を指定します。次のセクションでこのトリガーを使用して、コマンドに応答する必要があります。
1. HTTP エンドポイント URL: ここに共通の HTTP エンドポイント URL を 1 つ指定できます。または、トリガーごとに異なる HTTP エンドポイントを使用するには、[アプリコマンド] フィールドにエンドポイントを直接指定します。
2. Apps Script: Apps Script の Deployment ID を入力します。デフォルトでは、onAppCommand 関数が呼び出されます。別の Apps Script 関数を使用するには、[アプリコマンド] フィールドにカスタム関数名を指定します。
[コマンド] で [コマンドを追加] をクリックします。
コマンドに関する次の情報を入力します。
1. コマンド ID: Chat アプリがコマンドを認識してレスポンスを返すために使用する 1 ～ 1,000 の数字。
2. 説明: コマンドの使用方法と形式を説明するテキスト。説明文は半角 50 文字（全角 25 文字）以内で指定できます。
3. コマンドの種類: [クイックコマンド] または [スラッシュコマンド] を選択します。
4. クイックコマンドまたはスラッシュコマンドの名前を指定します。
  - クイックコマンド名: ユーザーがメニューから選択してコマンドを呼び出す表示名。最大 50 文字で、特殊文字を含めることができます。例: Remind me
  - スラッシュコマンド名: ユーザーがメッセージでコマンドを呼び出すために入力するテキスト。先頭はスラッシュにする必要があります。テキストのみを含めることができ、最大 50 文字です。例: /remindMe
省略可: Chat アプリがコマンドにダイアログで応答する場合は、[ダイアログを開く] チェックボックスをオンにします。
[保存] をクリックします。

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

コマンドに応答する

ユーザーがコマンドを使用すると、Chat アプリはイベントオブジェクトを受け取ります。イベントペイロードには、呼び出されたコマンドに関する詳細（コマンド ID やコマンドタイプなど）を含む appCommandPayload オブジェクトが含まれるため、適切なレスポンスを返すことができます。イベントオブジェクトは、アプリコマンド トリガーを構成したときに指定した HTTP エンドポイントまたは Apps Script 関数に送信されます。

Cymbal Labs のチャットアプリに関する非公開メッセージ。このメッセージには、チャットアプリが 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 events that contain payloads about commands
    if (chatEvent.appCommandPayload) {

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

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

  // 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 に置き換えてください。

コマンドをテストする

コマンドとコードをテストするには、Google Chat アプリのインタラクティブ機能をテストするをご覧ください。

Chat UI でコマンドをテストして使用する方法については、Google Chat ヘルプドキュメントの Google Chat でアプリを使用するをご覧ください。

Google Chat アプリのコマンドに応答する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

Chat アプリコマンドの種類

前提条件

HTTP

Apps Script

コマンドを設定する

コマンドの名前と説明を入力します

コマンドに名前を付けるには:

コマンドの説明を取得するには:

Google Cloud コンソールでコマンドを構成する

コマンドに応答する

Node.js

Apps Script

コマンドをテストする

関連トピック

Google Chat アプリのコマンドに応答する