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

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

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

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

前提条件

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

インタラクション イベントの種類

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

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

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

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

次の表に、一般的なユーザー操作、Chat アプリが受け取るインタラクション イベントのタイプ、Chat アプリの一般的な応答を示します。

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

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

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

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

次の表に、ダイアログとの一般的なインタラクション、対応するダイアログ イベントタイプ、Chat アプリの一般的な応答方法の説明を示します。

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

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

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

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

すべての Chat アプリがインタラクティブであるとは限りません。たとえば、 受信 Webhook は送信メッセージのみを送信でき、 ユーザーに応答できません。インタラクティブな 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 アプリを登録します。詳しくは、自然言語を理解する DialogflowGoogle Chat アプリを作成するをご覧ください。
   コマンド	省略可。Chat アプリのスラッシュ コマンドとクイック コマンド。コマンドを使用すると、ユーザーはアクションをリクエストしたり、Chat アプリの特定の機能を使用したりできます。詳しくは、Google Chat アプリのコマンドに応答するをご覧ください。
   リンク プレビュー	省略可。Chat アプリが認識し、ユーザーがリンクを送信したときに追加コンテンツを提供する URL パターン。詳しくは、リンクをプレビューするをご覧ください。
   公開設定	省略可。Chat アプリを表示してインストールできるユーザー（最大 5 人）または Google グループ（1 つ以上）。このフィールドを使用して、Chat アプリをテストしたり、チームと共有したりできます。詳しくは、インタラクティブ機能をテストするをご覧ください。

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

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

サービスへの 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 オブジェクトを含めることができます。他の種類のレスポンスで使用するには、次のガイドをご覧ください。

• インタラクティブなダイアログをサポートする
• リンクをプレビューする
• ユーザーが送信した情報を処理する

メッセージで応答

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

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

/**
 * 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`.'
    });
  }
};

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({})

@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();
    }
  }
}

/**
 * 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 アプリのインタラクティブ機能をテストする