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

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

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

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

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

Google Workspace アドオンとしてインタラクティブな Chat アプリを作成する

Chat ユーザーとやり取りする Chat アプリを構築するには、Chat を拡張する Google Workspace アドオンを構築します。Chat アプリは、Chat API からインタラクションイベントを受信するのではなく、アドオンイベントオブジェクトを受信して応答します。詳細については、Google Workspace アドオンのドキュメントで Google 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 アプリはすぐにスペースでウェルカムメッセージを返信できます。

チャットアプリがウェルカムメッセージを投稿します。 — **図 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`	チャットアプリは、別のダイアログに移動するか、ダイアログを閉じて操作を完了します。
ユーザーが情報を送信する前にダイアログを終了または閉じる。	`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 アプリとしてスラッシュコマンドに応答するをご覧ください。
リンクプレビュー	省略可。チャットアプリが認識し、ユーザーがリンクを送信したときに追加コンテンツを提供できる 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 アプリは Google Chat API を呼び出して非同期で応答できます。

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