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

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

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

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

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

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

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

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

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

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

次の図は、ユーザーがスラッシュコマンド、クイックコマンド、メッセージアクションのメニューを見つける方法を示しています。

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

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

前提条件

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 でコマンドを構成する手順は次のとおりです。

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

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

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

コマンドに応答する

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

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

次のコードは、スラッシュコマンド /about にテキストメッセージで応答する Chat アプリの例を示しています。スラッシュコマンドに応答するために、Chat アプリは [アプリコマンド] トリガーからのイベントオブジェクトを処理します。イベントオブジェクトのペイロードにスラッシュコマンド ID が含まれている場合、Chat アプリはアクション DataActions と createMessageAction オブジェクトを返します。

Node.js

node/chat/avatar-app/index.js

GitHub で表示

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Handle requests from Google Workspace add on
 *
 * @param {Object} req Request sent by Google Chat
 * @param {Object} res Response to be sent back to Google Chat
 */
http('avatarApp', (req, res) => {
  const chatEvent = req.body.chat;
  let message;
  if (chatEvent.appCommandPayload) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
    message: message
  }}}});
});

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 * @return the response message object.
 */
function handleAppCommand(event) {
  switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return {
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/chat/avatar-app/main.py

GitHub で表示

# The ID of the slash command "/about".
# You must use the same ID in the Google Chat API configuration.
ABOUT_COMMAND_ID = 1

@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
  """Handle requests from Google Workspace add on

  Args:
    flask.Request req: the request sent by Google Chat

  Returns:
    Mapping[str, Any]: the response to be sent back to Google Chat
  """
  chat_event = req.get_json(silent=True)["chat"]
  if chat_event and "appCommandPayload" in chat_event:
    message = handle_app_command(chat_event)
  else:
    message = handle_message(chat_event)
  return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
      "message": message
  }}}}

def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Responds to an APP_COMMAND event in Google Chat.

  Args:
    Mapping[str, Any] event: the event object from Google Chat

  Returns:
    Mapping[str, Any]: the response message object.
  """
  if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
    return {
      "text": "The Avatar app replies to Google Chat messages.",
    }
  return {}

Java

java/chat/avatar-app/src/main/java/com/google/chat/avatar/App.java

GitHub で表示

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
private static final int ABOUT_COMMAND_ID = 1;

private static final Gson gson = new Gson();

/**
 * Handle requests from Google Workspace add on
 * 
 * @param request the request sent by Google Chat
 * @param response the response to be sent back to Google Chat
 */
@Override
public void service(HttpRequest request, HttpResponse response) throws Exception {
  JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
  JsonObject chatEvent = event.getAsJsonObject("chat");
  Message message;
  if (chatEvent.has("appCommandPayload")) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  JsonObject createMessageAction = new JsonObject();
  createMessageAction.add("message", gson.fromJson(gson.toJson(message), JsonObject.class));
  JsonObject chatDataAction = new JsonObject();
  chatDataAction.add("createMessageAction", createMessageAction);
  JsonObject hostAppDataAction = new JsonObject();
  hostAppDataAction.add("chatDataAction", chatDataAction);
  JsonObject dataActions = new JsonObject();
  dataActions.add("hostAppDataAction", hostAppDataAction);
  response.getWriter().write(gson.toJson(dataActions));
}

/**
 * Handles an APP_COMMAND event in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return the response message object.
 */
private Message handleAppCommand(JsonObject event) throws Exception {
  switch (event.getAsJsonObject("appCommandPayload")
    .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
    case ABOUT_COMMAND_ID:
      return new Message()
        .setText("The Avatar app replies to Google Chat messages.");
    default:
      return null;
  }
}

Apps Script

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

GitHub で表示

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {
  // Executes the app command logic based on ID.
  switch (event.chat.appCommandPayload.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 に置き換えます。

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

次のコードは、メッセージアクション Remind me にテキストメッセージで応答する Chat アプリの例を示しています。メッセージアクションに応答するために、Chat アプリは [アプリコマンド] トリガーからのイベントオブジェクトを処理します。イベントオブジェクトのペイロードにメッセージアクションコマンド ID が含まれている場合、Chat アプリはアクション DataActionsと createMessageAction オブジェクトを返します。

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 onAppCommand(event, res) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} =
    event.chat.appCommandPayload.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.chat.appCommandPayload.message.text;

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

Python

def on_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.
    payload = event.get('chat', {}).get('appCommandPayload', {})
    metadata = payload.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 = payload.get('message', {}).get('text')

        # Return a response that includes details from the original message.
        return {
            "hostAppDataAction": {
                "chatDataAction": {
                    "createMessageAction": {
                        "message": {
                            "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 onAppCommand(JsonObject event, HttpResponse response) throws Exception {
  // Collect the command ID and type from the event metadata.
  JsonObject payload = event.getAsJsonObject("chat").getAsJsonObject("appCommandPayload");
  JsonObject metadata = payload.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 = payload.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);

      JsonObject createMessageAction = new JsonObject();
      createMessageAction.add("message", responseMessage);

      JsonObject chatDataAction = new JsonObject();
      chatDataAction.add("createMessageAction", createMessageAction);

      JsonObject hostAppDataAction = new JsonObject();
      hostAppDataAction.add("chatDataAction", chatDataAction);

      JsonObject finalResponse = new JsonObject();
      finalResponse.add("hostAppDataAction", hostAppDataAction);

      response.getWriter().write(finalResponse.toString());
    }
  }
}

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.chat.appCommandPayload.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.chat.appCommandPayload.message.text;

    // Return a response that includes details from the original message.
    return CardService.newChatResponseBuilder()
        .setText("Setting a reminder for message: " + messageText)
        .build();
  }
}

このコードサンプルを使用するには、Chat API でコマンドを構成したときに指定したコマンド ID で REMIND_ME_COMMAND_ID を置き換えます。

コマンドをテストする

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

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

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

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

前提条件

HTTP

Apps Script

コマンドを設定する

コマンドに名前を付けて説明する

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

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

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

コマンドに応答する

Node.js

Python

Java

Apps Script

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

Node.js

Python

Java

Apps Script

コマンドをテストする

関連トピック

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

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