インタラクション イベントを受け取って応答する

このページでは、Google Chat アプリがユーザー インタラクション（Google Chat アプリのインタラクション イベントとも呼ばれます）を受信して応答する方法について説明します。

このページでは、次の操作を行う方法について説明します。

• インタラクション イベントを受信するように Chat 用アプリを構成します。
• インフラストラクチャでインタラクション イベントを処理します。
• 必要に応じて、インタラクション イベントに応答します。

注: このガイドでは、Chat API のインタラクション イベントを使用してインタラクティブな Chat 用アプリを構築する方法について説明します。Chat 用アプリを Google Workspace アドオンとしてビルドすることもできます。使用するフレームワークについては、インタラクティブな Google Chat アプリを作成するをご覧ください。

前提条件

• Google Chat へのアクセス権を持つ Business または Enterprise の Google Workspace アカウント。
• Google Cloud プロジェクトを作成します。
• OAuth 同意画面を構成します。
• Google Chat API を有効にします。

操作イベントの種類

Google Chat 用アプリのインタラクション イベントは、ユーザーが Chat 用アプリを呼び出したり操作したりするために行うアクション（Chat 用アプリの @メンションやスペースへの追加など）を表します。

ユーザーが Chat 用アプリとやり取りすると、Google Chat は Chat 用アプリにインタラクション イベントを送信します。これは、Chat API の Event 型として表されます。Chat 用アプリは、このイベントを使用してインタラクションを処理し、必要に応じてメッセージで応答できます。

ユーザー インタラクションの種類ごとに、Google Chat は異なる種類の操作イベントを送信します。これにより、Chat 用アプリは各イベントの種類を適切に処理できます。インタラクション イベントのタイプは eventType オブジェクトを使用して表されます。

たとえば、Google Chat では、ユーザーが Chat 用アプリをスペースに追加するインタラクションにイベントタイプ ADDED_TO_SPACE を使用します。これにより、Chat 用アプリはすぐにスペースにウェルカム メッセージを返信できます。

図 1: ユーザーが Chat 用アプリをスペースに追加すると、Chat 用アプリは ADDED_TO_SPACE 操作イベントを受け取ります。このイベントを処理して、スペースにウェルカム メッセージを送信します。

次の表は、一般的なユーザー操作、Chat 用アプリが受け取る操作イベントのタイプ、Chat 用アプリの一般的なレスポンスを示しています。

ユーザーの操作	eventType	Chat 用アプリからの一般的なレスポンス
ユーザーが Chat 用アプリにメッセージを送信します。たとえば、Chat 用アプリの名前リンクを付けたり、スラッシュ コマンドを使用したりします。	MESSAGE	Chat 用アプリは、メッセージの内容に基づいて応答します。たとえば、Chat 用アプリは、スラッシュ コマンド /about に対して、Chat 用アプリが実行できるタスクを説明するメッセージで応答します。
ユーザーが Chat 用アプリをスペースに追加します。	ADDED_TO_SPACE	Chat 用アプリは、アプリの機能とスペースのユーザーがアプリを操作する方法を説明する オンボーディング メッセージを送信します。
ユーザーがスペースから Chat 用アプリを削除します。	REMOVED_FROM_SPACE	Chat 用アプリは、スペース用に構成された受信通知を削除し（Webhook の削除など）、内部ストレージをクリアします。
ユーザーが Chat 用アプリのメッセージ、ダイアログ、ホームページのカードにあるボタンをクリックします。	CARD_CLICKED	Chat 用アプリは、ユーザーが送信したデータを処理して保存するか、別のカードを返します。
ユーザーが 1 対 1 のメッセージで [ホーム] タブをクリックして、Chat 用アプリのホームページを開きます。	APP_HOME	Chat 用アプリは、ホームページから静的カードまたはインタラクティブ カードを返します。
ユーザーが Chat 用アプリのホームページからフォームを送信します。	SUBMIT_FORM	Chat 用アプリは、ユーザーが送信したデータを処理して保存するか、別のカードを返します。
ユーザーがクイック コマンドを使用してコマンドを呼び出す。	APP_COMMAND	Chat 用アプリは、呼び出されたコマンドに基づいて応答します。たとえば、Chat 用アプリは About コマンドに対して、Chat 用アプリで実行できるタスクを説明するメッセージで応答します。

サポートされているすべてのインタラクション イベントについては、EventType リファレンス ドキュメントをご覧ください。

ダイアログからのインタラクション イベント

Chat 用アプリがダイアログを開く場合、インタラクション イベントには、レスポンスの処理に使用できる次の追加情報が含まれます。

• isDialogEvent は true に設定します。
• DialogEventType は、インタラクションによってダイアログが開くのか、ダイアログから情報が送信されるのか、ダイアログが閉じられるのかを明確にします。

次の表に、ダイアログの一般的な操作、対応するダイアログ イベントタイプ、Chat 用アプリが通常どのように応答するかを示します。

ユーザー インタラクションによるダイアログの操作	ダイアログ イベントのタイプ	一般的な対応
ユーザーがダイアログ リクエストをトリガーします。たとえば、スラッシュ コマンドを使用したり、メッセージのボタンをクリックしたりします。	REQUEST_DIALOG	Chat アプリでダイアログが開きます。
ユーザーがボタンをクリックしてダイアログで情報を送信します。	SUBMIT_DIALOG	Chat 用アプリは、別のダイアログに移動するか、ダイアログを閉じてインタラクションを完了します。
ユーザーが情報を送信する前にダイアログを終了または閉じます。	CANCEL_DIALOG	必要に応じて、Chat 用アプリは新しいメッセージで応答したり、ユーザーがダイアログを開いたメッセージやカードを更新したりできます。

詳しくは、インタラクティブなダイアログをサポートするをご覧ください。

Chat 用アプリのインタラクション イベントを受信する

このセクションでは、Chat 用アプリのインタラクション イベントを受信して処理する方法について説明します。

インタラクション イベントを受信するように Chat 用アプリを構成する

すべての Chat 用アプリがインタラクティブであるわけではありません。たとえば、インバウンド ウェブフックは送信メッセージのみを送信でき、ユーザーに応答することはできません。インタラクティブな Chat 用アプリを構築する場合は、Chat 用アプリがインタラクション イベントを受信、処理、応答できるエンドポイントを選択する必要があります。Chat 用アプリの設計について詳しくは、Chat 用アプリの実装アーキテクチャをご覧ください。

構築するインタラクティブ機能ごとに、Google Chat が関連するインタラクション イベントを Chat 用アプリに送信できるように、Chat API で構成を更新する必要があります。

1. Google Cloud コンソールで、Chat API ページに移動し、[構成] ページをクリックします。

   [Chat API の構成] ページに移動

2. [インタラクティブ機能] で、設定を確認し、構築する機能に基づいて更新します。

   フィールド	説明
   機能	必須。Chat 用アプリがユーザーとやり取りする方法を決定する一連のフィールド。デフォルトでは、ユーザーは Google Chat で直接 Chat 用アプリを見つけてメッセージを送信できます。 スペースとグループの会話に参加する: ユーザーは Chat 用アプリをスペースやグループの会話に追加できます。
   接続設定	必須。Chat 用アプリのエンドポイント。次のいずれかです。 HTTP エンドポイント URL: Chat 用アプリの実装をホストする HTTPS エンドポイント。 Apps Script: Chat 用アプリを実装する Apps Script プロジェクトのデプロイ ID。 Cloud Pub/Sub トピック名: Chat 用アプリがエンドポイントとしてサブスクライブする Pub/Sub トピック。 Dialogflow: Dialogflow との統合に Chat 用アプリを登録します。詳細については、自然言語を理解する Dialogflow Google Chat アプリを構築するをご覧ください。
   コマンド	省略可。Chat 用アプリのスラッシュ コマンドとクイック コマンド。コマンドを使用すると、ユーザーはアクションをリクエストしたり、Chat 用アプリの特定の機能を使用したりできます。詳しくは、Google Chat 用アプリのコマンドに応答するをご覧ください。
   スターター プロンプト	省略可。（ デベロッパー プレビュー） ユーザーが Chat 用アプリで空の 1 対 1 のダイレクト メッセージを開いたときに表示される、最大 3 つのゼロ状態プロンプト。プロンプトは、作成エリアにテキストを入力したり（多言語ローカライズのサポートあり）、スラッシュ コマンドやクイック コマンドを直接トリガーしたりできます。詳細については、スターター プロンプトを構成するをご覧ください。
   リンク プレビュー	省略可。チャットアプリが認識でき、ユーザーがリンクを送信したときに追加コンテンツを提供できる URL パターン。詳しくは、リンクをプレビューするをご覧ください。
   公開設定	省略可。Chat 用アプリを表示してインストールできる個人（最大 5 人）または 1 つ以上の Google グループ。このフィールドを使用して、Chat 用アプリをテストしたり、チームと共有したりします。詳しくは、インタラクティブ機能をテストするをご覧ください。

3. [保存] をクリックします。Chat 用アプリの構成を保存すると、Google Workspace 組織内の指定されたユーザーが Chat 用アプリを使用できるようになります。

これで、Google Chat からのインタラクション イベントを受信するように Chat 用アプリが構成されました。

スターター プロンプトを設定する

デベロッパー プレビュー: Google Workspace デベロッパー プレビュー プログラムの一部として利用できます。このプログラムでは、特定の機能に早期アクセスできます。

スターター プロンプトは、ユーザーがアプリとの 1 対 1 の空のダイレクト メッセージを開いたときに、Chat 用アプリの機能を見つけるのに役立ちます。スターター プロンプトは最大 3 つまで設定できます。

開始プロンプトを追加して構成するには:

1. Google Cloud コンソールで、Chat API の [構成] ページに移動します。

   [Chat API の構成] ページに移動

2. [インタラクティブ機能] で [スターター プロンプト] を見つけて、[プロンプトを追加] をクリックします。

3. [ランク（1 ～ 3）] フィールドに 1～3 の数値を入力して、表示順序を指定します。

4. [タイプ選択] で、プロンプトの動作を選択します。

   • テキスト プロンプト: ユーザーがプロンプト チップをクリックすると、入力バーに事前定義されたテキストが入力されます。
   • コマンド プロンプト: クリックすると、登録済みのスラッシュ コマンドまたはクイック コマンドが実行されます。追加の引数を必要とするコマンドは選択できません。

5. 選択したタイプに基づいてプロンプトを構成します。

   • [テキスト プロンプト] を選択した場合:

     1. [タイトル] に、チップに表示されるプロンプトのタイトルを入力します（半角 30 文字（全角 15 文字）まで）。
     2. [プロンプト テキスト] に、入力バーに表示されるテキストを入力します（最大 60 文字）。
     3. 省略可: 他の言語のユーザー向けにローカライズされたタイトルとテキストを追加します。
     4. [ローカライズされたプロンプト] で、[言語を追加] をクリックします。
     5. [言語] で、プルダウンからサポートされている言語を選択します。
     6. [Localized Title] に、ローカライズされたタイトルを入力します（半角 30 文字（全角 15 文字）まで）。
     7. [ローカライズされたプロンプト テキスト] に、ローカライズされたプロンプト テキスト（最大 60 文字）を入力します。
     8. 必要に応じて、この操作を繰り返して言語を追加します。

   • [コマンド プロンプト] を選択した場合:

     1. [スラッシュ コマンド / クイック コマンド] で、プルダウンからコマンドを選択します。

6. [完了] をクリックし、ページの下部にある [保存] をクリックします。

サービスへの HTTP 呼び出しの再試行を処理する

サービスへの HTTPS リクエストが失敗した場合（タイムアウト、一時的なネットワーク障害、2xx 以外の HTTPS ステータス コードなど）、Google Chat は数分以内に数回配信を再試行することがあります（ただし、保証されるものではありません）。その結果、特定の状況では、Chat 用アプリが同じメッセージを数回受信することがあります。リクエストが正常に完了しても、無効なメッセージ ペイロードが返された場合、Google Chat はリクエストを再試行しません。

インタラクション イベントを処理または応答する

このセクションでは、Google Chat 用アプリがインタラクション イベントを処理して応答する方法について説明します。

Chat 用アプリが Google Chat からインタラクション イベントを受信した後、さまざまな方法で応答できます。多くの場合、インタラクティブな Chat 用アプリはメッセージでユーザーに返信します。Google Chat アプリは、データソースから情報を検索したり、インタラクション イベント情報を記録したりすることもできます。この処理動作は、基本的に Google Chat アプリを定義するものです。

同期的に応答するには、Chat 用アプリは 30 秒以内に応答する必要があります。また、応答はやり取りが発生したスペースに投稿する必要があります。それ以外の場合、Chat 用アプリは非同期で応答できます。

インタラクション イベントごとに、Chat 用アプリはイベントを表す JSON ペイロードであるリクエスト本文を受け取ります。この情報を使用してレスポンスを処理できます。イベント ペイロードの例については、Chat 用アプリのインタラクション イベントの種類をご覧ください。

次の図は、Google Chat 用アプリが通常、さまざまな種類のインタラクション イベントを処理または応答する方法を示しています。

リアルタイムで回答を表示

インタラクション イベントを使用すると、Chat 用アプリはリアルタイムで、または同期的に応答できます。同期レスポンスには認証は必要ありません。

リアルタイムで応答するには、Chat 用アプリが Message オブジェクトを返す必要があります。スペースでメッセージで返信するには、Message オブジェクトに text、cardsV2、accessoryWidgets オブジェクトを含めることができます。他のタイプのレスポンスで使用する場合は、次のガイドをご覧ください。

• インタラクティブ ダイアログを開く
• プレビュー リンク
• ユーザーから送信された情報を処理する

注: REMOVED_FROM_SPACE インタラクション イベントの場合、Chat 用アプリはスペースに存在しなくなったため、Message オブジェクトで応答できません。

メッセージで応答

この例では、Chat 用アプリがスペースに追加されるたびにテキスト メッセージを作成して送信します。ユーザーのオンボーディングに関するベスト プラクティスについては、ユーザーに Chat 用アプリを紹介するをご覧ください。

ユーザーがスペースに Chat 用アプリを追加したときにテキスト メッセージを送信するには、Chat 用アプリが ADDED_TO_SPACE インタラクション イベントに応答します。ADDED_TO_SPACE インタラクション イベントにテキスト メッセージで応答するには、次のコードを使用します。

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar
      from Google Chat. Take a look at your schedule today by typing
      `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
      learn what else I can do, type `/help`.'
    });
  }
};

Python

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar' +
      'from Google Chat. Take a look at your schedule today by typing' +
      '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To' +
      'learn what else I can do, type `/help`.'
    })
  return json.jsonify({})

Java

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return new Message().setText(
          "Hi, Cymbal at your service. I help you manage your calendar" +
          "from Google Chat. Take a look at your schedule today by typing" +
          "`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`." +
          "To learn what else I can do, type `/help`.");
      default:
        return new Message();
    }
  }
}

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onAddToSpace(event) {
  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar
    from Google Chat. Take a look at your schedule today by typing
    `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
    what else I can do, type `/help`.'
  }
}

このコードサンプルは、次のテキスト メッセージを返します。

非同期で応答する

Chat 用アプリは、30 秒後にインタラクション イベントに応答するか、インタラクション イベントが生成されたスペースの外部でタスクを実行しなければならない場合があります。たとえば、Chat 用アプリは、長時間実行タスクの完了後にユーザーに応答する必要がある場合があります。この場合、Chat 用アプリは Google Chat API を呼び出して非同期で応答できます。

Chat API を使用してメッセージを作成するには、メッセージを作成するをご覧ください。その他の Chat API メソッドの使用に関するガイドについては、Chat API の概要をご覧ください。

関連トピック

• メッセージを送信する
• インタラクティブ ダイアログを開く
• プレビュー リンク
• カード上のユーザーが入力したフォームデータを読み取る
• コマンドに応答する
• Chat 用アプリのホームページを作成する
• Chat からのリクエストを確認する
• Google Chat 用アプリのインタラクティブ機能をテストする