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

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

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

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

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

Chat API の構成ページに移動

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

フィールド	説明
機能	必須。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 用アプリが認識して追加コンテンツを提供する URL パターン。詳しくは、リンクのプレビューをご覧ください。
公開設定	省略可。Chat 用アプリを表示してインストールできる個人（最大 5 人）または 1 つ以上の Google グループ。このフィールドを使用して、Chat 用アプリをテストしたり、チームと共有したりします。詳しくは、インタラクティブ機能をテストするをご覧ください。

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

Chat アプリが構成され、Google 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 用アプリがさまざまな種類のインタラクションイベントを処理または応答する方法を示しています。

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

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

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

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

非同期で応答する

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

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