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

ユーザーの操作を受信して応答する

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

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

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

前提条件

インタラクティブ機能が有効になっている Google Chat アプリ。インタラクティブな Chat アプリを作成するには、使用するアプリアーキテクチャに基づいて、次のいずれかのクイックスタートを行います。

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

Google Chat アプリの操作イベントは、Chat 用アプリへの名前リンクやスペースへの追加など、ユーザーが Chat 用アプリを呼び出したり操作したりするアクションを表します。

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

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

たとえば、Google Chat では、ユーザーが Chat アプリをスペースに追加する操作に対してイベントタイプ ADDED_TO_SPACE が使用されるため、Chat アプリはすぐにスペースでウェルカムメッセージを返信できます。

Chat アプリからウェルカムメッセージが投稿されます。 — **図 1**: ユーザーがスペースに Chat アプリを追加すると、Chat アプリは `ADDED_TO_SPACE` インタラクションイベントを受信し、Chat アプリはスペースにウェルカムメッセージを送信するためにこれを処理します。

次の表に、一般的なユーザー操作、Chat アプリが受信するインタラクションイベントの種類、Chat アプリが通常どのように応答するかを示します。

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

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

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

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

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

次の表に、ダイアログとの一般的なやり取り、対応するダイアログイベントの種類、Chat アプリが通常どのように応答するかを示します。

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

詳細については、ダイアログを開いて応答するをご覧ください。

Chat アプリの操作イベントを受信する

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

操作イベントを受信するように Chat アプリを構成する

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

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

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

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

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

フィールド	説明
機能	必須。Chat アプリがユーザーとやり取りする方法を決定する一連のフィールド: 1 対 1 のメッセージを受信する: ユーザーは 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 アプリを構築するをご覧ください。
スラッシュコマンド	省略可。Google Chat 内でユーザーに表示できるコマンド。ユーザーは Google Chat 内で Chat アプリのコアアクションを確認し、操作する特定のアクションを選択できます。詳細については、Chat 用アプリとしてスラッシュコマンドに応答するをご覧ください。
リンクプレビュー	省略可。ユーザーがリンクを送信したときに Chat アプリが認識して追加のコンテンツを提供する URL パターン。詳細については、プレビューリンクをご覧ください。
公開設定	省略可。Chat 用アプリを表示およびインストールできるユーザー（最大 5 人）または Google グループ（1 つ以上）。このフィールドは、Chat 用アプリをテストする場合や、Chat 用アプリをチームと共有する場合に使用します。詳細については、インタラクティブ機能をテストするをご覧ください。

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

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

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

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

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

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

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

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

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

次の図は、Google Chat アプリがさまざまな種類のインタラクションイベントをどのように処理または応答するかを示しています。

Google Chat アプリがインタラクションイベントを処理するアーキテクチャ。

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

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

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

メッセージで応答

この例では、スペースにテキストメッセージが追加されるたびに、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. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

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

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. An onboarding message that
 * introduces the app and helps people get started with it.
 */
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`.'
  }
}

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

オンボーディングメッセージの例。

非同期で応答する

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

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