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

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

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

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

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

Chat アプリコマンドの種類

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

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

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

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

前提条件

Node.jsApps ScriptPythonJava

インタラクティブ機能が有効になっている Google Chat アプリ。HTTP サービスを使用してインタラクティブな Chat アプリを作成するには、こちらのクイックスタートを完了してください。

インタラクティブ機能が有効になっている Google Chat アプリ。Apps Script でインタラクティブな Chat アプリを作成するには、こちらのクイックスタートを完了してください。

コマンドを設定する

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

コマンドに名前と説明を作成します。
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 でコマンドを構成する手順は次のとおりです。

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

Google Chat API ページに移動
[構成] をクリックします。
[コマンド] で [コマンドを追加] をクリックします。
コマンドのコマンド ID、名前、説明、コマンドタイプを入力します。
- コマンド ID: Chat アプリがコマンドの認識とレスポンスを返すために使用する 1 ～ 1,000 の数字。
- 名前: コマンドの表示名。名前は 50 文字までで、特殊文字を含めることができます。
- 説明: コマンドの機能の説明。説明は 50 文字以内で、特殊文字を含めることができます。
- コマンドの種類: [クイックコマンド] または [スラッシュコマンド] を選択します。
- スラッシュコマンドを構成する場合は、[スラッシュコマンド名] フィールドに値を入力して、ユーザーがコマンドを呼び出すために入力する内容を指定します。先頭はスラッシュにする必要があります。テキストのみを含めることができ、最大 50 文字です。例: /remindMe
省略可: Chat アプリがコマンドにダイアログで応答する場合は、[ダイアログを開く] チェックボックスをオンにします。
[保存] をクリックします。

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

コマンドに応答する

ユーザーがコマンドを使用すると、Chat アプリはインタラクションイベントを受信します。イベントペイロードには、呼び出されたコマンドに関する詳細（コマンド ID やコマンドタイプなど）を含むメタデータが含まれるため、適切なレスポンスを返すことができます。

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

各タイプのコマンドに応答するには、イベントペイロードでさまざまなイベントタイプとメタデータオブジェクトを処理する必要があります。

コマンドタイプ	イベントの種類	コマンドメタデータ
スラッシュコマンド	`MESSAGE`	`message.slashCommand` / `message.annotation.slashCommand`
クイックコマンド	`APP_COMMAND`	`appCommandMetadata`

メッセージでコマンドに返信する方法については、次のセクションをご覧ください。

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

次のコードは、スラッシュコマンド /about に返信する Chat アプリの例を示しています。Chat アプリは MESSAGE インタラクションイベントを処理し、インタラクションイベントに一致するコマンド ID が含まれているかどうかを検出して、非公開メッセージを返します。

Node.js Apps Script PythonJava

node/avatar-app/index.js

GitHub で表示

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

apps-script/avatar-app/avatar-app.gs

GitHub で表示

// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

python/avatar-app/main.py

GitHub で表示

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

java/avatar-app/src/main/java/AvatarApp.java

GitHub で表示

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

ABOUT_COMMAND_ID は、Google Cloud コンソールでコマンドを構成したときに指定したコマンド ID に置き換えます。

クイックコマンドに応答する

次のコードは、クイックコマンド「Help」に返信する Chat アプリの例を示しています。Chat アプリは APP_COMMAND インタラクションイベントを処理し、インタラクションイベントに一致するコマンド ID が含まれているかどうかを検出して、非公開メッセージを返します。

Node.js Apps Script PythonJava

node/avatar-app/index.js

GitHub で表示

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

apps-script/avatar-app/avatar-app.gs

GitHub で表示

// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

python/avatar-app/main.py

GitHub で表示

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

java/avatar-app/src/main/java/AvatarApp.java

GitHub で表示

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

HELP_COMMAND_ID は、Google Cloud コンソールでコマンドを構成したときに指定したコマンド ID に置き換えます。

コマンドをテストする

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

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

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

Chat アプリコマンドの種類

前提条件

コマンドを設定する

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

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

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

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

コマンドに応答する

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

クイック コマンドに応答する

コマンドをテストする

関連トピック

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

クイックコマンドに応答する