Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

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

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

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

Chat 用アプリのコマンドの種類

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

スラッシュコマンド: メニューからスラッシュコマンドを選択するか、スラッシュ（/）を入力してから、/about などの事前定義されたテキストを入力します。通常、Chat 用アプリではスラッシュコマンドの引数テキストが必要です。

Chat 用アプリでユーザーからの追加の入力が必要な場合は、スラッシュコマンドを作成します。たとえば、ユーザーが検索するフレーズ（/search receipts など）を入力した後に実行される /search というスラッシュコマンドを作成できます。
クイックコマンド: ユーザーは、Chat メッセージの返信欄からメニューを開いてコマンドを使用します。コマンドを使用するには、[追加] をクリックし、メニューからコマンドを選択します。

Chat 用アプリが追加の入力を待たずにユーザーにすぐに返信できる場合は、クイックコマンドを作成します。たとえば、ランダムな画像というクイックコマンドを作成して、画像ですぐに応答できるようにします。
メッセージアクション: （デベロッパープレビュー）ユーザーは、メッセージにカーソルを合わせてその他メニューをクリックすることで、メッセージアクションを使用します。コマンドを使用するには、その他メニューを開き、メニューからコマンドを選択します。

Chat 用アプリがメッセージのコンテキストに基づいてアクションを実行できる場合は、メッセージアクションを作成します。

次の画像は、ユーザーがスラッシュコマンドとクイックコマンドのメニュー、メッセージアクションをどのように見つけるかを示しています。

ユーザーがスラッシュコマンドとクイックコマンドのメニューを見つけます。 — ユーザーは、スラッシュコマンドとクイックコマンドのメニューを見つけます。

ユーザーがメッセージ操作を含むメッセージコンテキストメニューを見つけます。 — ユーザーが、[リマインダー] メッセージアクションを含むメッセージコンテキストメニューを見つけます。

前提条件

Node.js

インタラクションイベントを受信して応答する Google Chat 用アプリ。HTTP サービスを使用してインタラクティブな Chat 用アプリを作成するには、このクイックスタートを完了してください。

Apps Script

インタラクションイベントを受信して応答する Google Chat 用アプリ。Apps Script で双方向の Chat 用アプリを作成するには、このクイックスタートを完了してください。

Python

Java

コマンドを設定する

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

コマンドの名前と説明を作成します。
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 文字以内で、特殊文字を含めることができます。例: Remind me
  - スラッシュコマンド名: ユーザーがメッセージ内でコマンドを呼び出すために入力するテキスト。先頭はスラッシュにする必要があります。含めることができるのはテキストのみで、最大 50 文字です。例: /remindMe
  - メッセージアクション名: （デベロッパープレビュー）ユーザーがメニューから選択してメッセージアクションを呼び出すときに表示される名前。半角 50 文字以内で、特殊文字を含めることができます。例: Remind me
省略可: 読み込み通知メッセージ: （デベロッパープレビュー）メッセージアクションの実行中にユーザーに表示するトースト通知メッセージ。ダイアログを開かないメッセージアクションでのみ使用できます。
省略可: Chat 用アプリがコマンドにダイアログで応答するようにするには、[ダイアログを開く] チェックボックスをオンにします。
[保存] をクリックします。

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

コマンドに応答する

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

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

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

コマンドタイプ	イベントの種類	コマンドメタデータ
スラッシュコマンド	`MESSAGE`	`message.slashCommand` または `message.annotation.slashCommand`
クイックコマンド	`APP_COMMAND`	`appCommandMetadata`
メッセージ操作	`APP_COMMAND`	`appCommandMetadata`

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

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

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

Node.js

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

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

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

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

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

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

GitHub で表示

/**
 * Handles the APP_COMMAND event type. This function is triggered when a user
 * interacts with a quick command within the Google Chat app.  It responds
 * based on the command ID.
 *
 * @param {Object} event The event object from Google Chat, containing details
 *     about the app command interaction.  It includes information like the
 *     command ID and the user who triggered it.
 */
function onAppCommand(event) {
  // Executes the quick command logic based on its ID.
  // Command IDs are set in the Google Chat API configuration.
  switch (event.appCommandMetadata.appCommandId) {
    case HELP_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

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

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 に置き換えます。

メッセージアクションに応答する

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

Node.js

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @param {Object} res The HTTP response object.
 * @return {Object} The JSON response message with a confirmation.
 */
function handleAppCommand(event, res) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  // Use appCommandType to detect message actions.
  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.message.text;

    // Return a response that includes details from the original message.
    return res.send({
      text: `Setting a reminder for this message: "${messageText}"`
    });
  }
}

Apps Script

/**
 * Responds to an APP_COMMAND interaction event in Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @return {Object} The JSON response message with a confirmation.
 */
function onAppCommand(event) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.message.text;

    // Return a response that includes details from the original message.
    return { "text": "Setting a reminder for message: " + messageText };
  }
}

Python

def handle_app_command(event):
    """Responds to an APP_COMMAND interaction event from Google Chat.

    Args:
        event (dict): The interaction event from Google Chat.

    Returns:
        dict: The JSON response message with a confirmation.
    """
    # Collect the command ID and type from the event metadata.
    metadata = event.get('appCommandMetadata', {})
    if metadata.get('appCommandType') == 'MESSAGE_ACTION' and \
       metadata.get('appCommandId') == REMIND_ME_COMMAND_ID:

        # Message actions can access the context of the message they were
        # invoked on, such as the text or sender of that message.
        message_text = event.get('message', {}).get('text')

        # Return a response that includes details from the original message.
        return {
            "text": f'Setting a reminder for message: "{message_text}"'
        }

Java

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param event The interaction event from Google Chat.
 * @param response The HTTP response object.
 */
void handleAppCommand(JsonObject event, HttpResponse response) throws Exception {
  // Collect the command ID and type from the event metadata.
  JsonObject metadata = event.getAsJsonObject("appCommandMetadata");
  String appCommandType = metadata.get("appCommandType").getAsString();

  if (appCommandType.equals("MESSAGE_ACTION")) {
    int commandId = metadata.get("appCommandId").getAsInt();
    if (commandId == REMIND_ME_COMMAND_ID) {
      // Message actions can access the context of the message they were
      // invoked on, such as the text or sender of that message.
      String messageText = event.getAsJsonObject("message").get("text").getAsString();

      // Return a response that includes details from the original message.
      JsonObject responseMessage = new JsonObject();
      responseMessage.addProperty("text", "Setting a reminder for message: " + messageText);
      response.getWriter().write(responseMessage.toString());
    }
  }
}

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

コマンドをテストする

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

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

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

Chat 用アプリのコマンドの種類

前提条件

Node.js

Apps Script

Python

Java

コマンドを設定する

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

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

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

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

コマンドに応答する

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

Node.js

Apps Script

Python

Java

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

Node.js

Apps Script

Python

Java

メッセージ アクションに応答する

Node.js

Apps Script

Python

Java

コマンドをテストする

関連トピック

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

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

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

メッセージアクションに応答する