Google Chat インターフェースを構築する

このページでは、Google Chat を拡張する Google Workspace アドオンのユーザー インターフェース（UI）を作成する方法の概要について説明します。

Google Chat では、アドオンは Google Chat アプリとしてユーザーに表示されます。詳細については、Google Chat の拡張機能の概要をご覧ください。

Chat 用アプリのインターフェースを構築するには、次のアドオン コンポーネントを使用します。

  • トリガー: Google Chat ユーザーが Chat アプリを呼び出す方法（スペースへの追加、メッセージの送信など）。
  • イベント オブジェクト: Chat アプリがトリガーまたは UI 操作から受け取るデータ。
  • アクション: メッセージの送信やカードベースのユーザー インターフェースの返却など、Chat アプリがインタラクションに応答する方法。
Chat アプリが、スペースへの追加トリガーからイベント オブジェクトを受信する
図 1: ユーザーが Chat アプリをスペースに追加すると、Added to space トリガーがトリガーされ、イベント オブジェクトが送信されます。メッセージで返信するには、Chat アプリがイベント オブジェクトを処理し、メッセージを作成するアクションを返します。

Chat アプリは、次のインターフェースでカードを作成して表示できます。

  • メッセージ: テキスト、静的カードまたはインタラクティブ カード、ボタンを含めることができます。
  • ダイアログ: 新しいウィンドウで開くカードで、通常はユーザーに情報を送信するよう求めるメッセージが表示されます。
  • リンク プレビュー: 外部サービスに関する情報をプレビューするカードです。

トリガー

このセクションでは、Google Workspace アドオンが Chat で使用するトリガーについて説明します。

トリガーとは、ユーザーが Chat UI を使用して Chat アプリを呼び出す特定の方法です（@ メンションやアプリコマンドなど）。

次の表に、Chat トリガー、説明、Chat アプリの一般的な応答方法を示します。

トリガー 説明 一般的な回答
スペースに追加しました

ユーザーが Chat アプリをスペースに追加するか、Google Workspace 管理者が組織内のユーザー向けのダイレクト メッセージ スペースに Chat アプリをインストールします。管理者がインストールする Chat アプリについては、Google Workspace 管理者向けヘルプドキュメントのドメイン内に Marketplace アプリをインストールするをご覧ください。

 Chat アプリは、その機能とスペース内のユーザーがどのように操作できるかを説明するオンボーディング メッセージを送信します。
メッセージ

ユーザーが次のいずれかの方法で、メッセージ内の Chat アプリを操作します。

  • Chat アプリでダイレクト メッセージ（DM）スペースにメッセージを送信します。
  • 任意の種類のスペースで Chat アプリを @ メンションします。
  • リンク プレビューの URL パターンに一致するリンクを含むメッセージを送信します。
  • selectionInput ウィジェットの複数選択メニューにテキストを入力します。
 Chat アプリは、メッセージの内容に基づいて応答します。たとえば、Chat アプリは /about コマンドに、Chat アプリが実行できるタスクを説明するメッセージを返します。
スペースから削除

ユーザーがスペースから Chat アプリを削除した場合、または Google Workspace 管理者が組織内のユーザーの Chat アプリをアンインストールした場合。

管理者がインストールした Chat 用アプリは、ユーザーが削除することはできません。ユーザーが Chat アプリを以前にインストールしていた場合、Google Workspace 管理者がアンインストールしようとしたかどうかにかかわらず、Chat アプリはインストールされたままになります。

 Chat アプリは、スペース用に構成された受信通知（Webhook の削除など）を削除し、内部ストレージを消去します。チャットアプリはスペースのメンバーではなくなったため、このトリガーにメッセージで返信することはできません。
アプリ コマンド

ユーザーが Chat アプリからクイック コマンドまたはスラッシュ コマンドを使用します。

 Chat アプリがコマンドに応答します。（例: メッセージで返信する、ダイアログを開く）。

他の Google Workspace アドオンとは異なり、これらのトリガーのコールバック関数は Google Chat API を使用して構成する必要があります。ガイダンスについては、Google Chat アプリを構成するをご覧ください。

トリガーに応答するには、次のガイドをご覧ください。

イベント オブジェクト

このセクションでは、Chat イベント オブジェクトのすべての要素について定義と説明を行います。詳細については、イベント オブジェクトをご覧ください。

イベント オブジェクト
commonEventObject object (CommonEventObject)
ホスト アプリケーションに関係なく、すべてのイベント オブジェクトに共通する情報が含まれるオブジェクト。
chat object (Chat)
Chat のインタラクションに関するすべての情報が含まれるオブジェクト。

チャット

チャット
chat.user object (User)
Chat アプリを操作した Chat ユーザー。
chat.space object (Space)
ユーザーが Chat アプリを操作した Chat スペース。
chat.eventTime

string (Timestamp format)

インタラクションが発生した日時。

共用体フィールド payload。

payload は次のいずれかになります。
chat.messagePayload

object (MessagePayload)

Chat アプリがメッセージ トリガーから受信するペイロード。
chat.addedToSpacePayload

object (AddedToSpacePayload)

Chat アプリが Added to space トリガーから受け取るペイロード。
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

Chat アプリが スペースから削除トリガーから受け取るペイロード。
chat.buttonClickedPayload

object (ButtonClickedPayload)

ユーザーがメッセージまたはカードのボタンをクリックしたときに Chat アプリが受け取るペイロード。ユーザーがボタンをクリックして情報を送信すると、commonEventObject.formInputs オブジェクトにユーザーから収集された値が含まれます。詳しくは、 Google Chat ユーザーから情報を収集するをご覧ください。
chat.widgetUpdatedPayload

object (WidgetUpdatedPayload)

ユーザーが selectionInput ウィジェットのマルチ選択メニューにテキストを入力したときに、Chat アプリが受信するペイロード。チャットアプリでは、このイベント オブジェクトを使用して、動的データソースから候補アイテムを入力できます。たとえば、外部データソースからサポートケースを入力するには、チャットアプリがユーザーがメニューに入力した内容に基づいてデータソースをクエリし、一致するサポートケースを選択可能なアイテムとして返します。

CommonEventObject.parameters['autocomplete_widget_query'] オブジェクトには、ユーザーがメニューに入力した文字列値が含まれます。
chat.appCommandPayload

object (AppCommandPayload)

ユーザーが Chat アプリのコマンドを使用すると、Chat アプリが受信するペイロード。

ペイロード

インタラクションの種類に応じて、イベントには 1 つ以上の Chat API リソースを含むペイロードが含まれます。

メッセージ ペイロード
MessagePayload
chat.messagePayload.message object (Message)
イベントをトリガーした Chat メッセージ。
chat.messagePayload.space object (Space)
ユーザーが Chat アプリを呼び出すメッセージを送信した Chat スペース。

スペースのペイロードに追加されました
AddedToSpacePayload
chat.addedToSpacePayload.space object (Space)
ユーザーが Chat アプリを追加またはインストールした Chat スペース。

管理者が Chat アプリをインストールすると、space.adminInstalled フィールドは true に設定されます。
chat.addedToSpacePayload.interactionAdd boolean
メッセージを使用してユーザーが Chat アプリをスペースに追加したかどうか。たとえば、Chat アプリを @ メンションしたり、スラッシュ コマンドを使用したりします。true の場合、Chat は、メッセージに関する情報を含む messagePayload を含む別のイベント オブジェクトを送信します。

スペース ペイロードから削除
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
ユーザーが Chat アプリを削除またはアンインストールした Chat スペース。

管理者が Chat アプリをアンインストールすると、space.adminInstalled フィールドは false に設定されます。

ボタンクリック ペイロード
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
ユーザーがクリックしたボタンを含む Chat メッセージ。
chat.buttonClickedPayload.space object (Space)
ユーザーが Chat アプリのメッセージからボタンをクリックした Chat スペース。
chat.buttonClickedPayload.isDialogEvent boolean
ユーザーがボタンをクリックしてダイアログを操作したかどうか。
chat.buttonClickedPayload.dialogEventType enum (DialogEventType)
isDialogEvent が true の場合、ダイアログ内のインタラクションのタイプ。

列挙型 DialogEventType。

dialogEventType の値は、次のいずれかの 1 つのみを指定できます。
TYPE_UNSPECIFIED デフォルト値。（指定なし）
REQUEST_DIALOG ユーザーがダイアログをリクエストします。たとえば、スラッシュ コマンドを使用するか、メッセージのボタンをクリックします。
SUBMIT_DIALOG ユーザーがダイアログ内のインタラクティブな要素をクリックします。たとえば、ユーザーがダイアログで情報を入力し、ボタンをクリックして情報を送信します。

ウィジェットの更新ペイロード
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
インタラクションが発生した Chat スペース。

アプリ コマンド ペイロード
AppCommandPayload
chat.appCommandPayload.appCommandMetadata object (AppCommandMetadata)
ユーザーが使用したコマンドと、コマンドをトリガーした方法に関するメタデータ。
chat.appCommandPayload.space object (Space)
ユーザーがコマンドを使用した Chat スペース。
chat.appCommandPayload.thread object (Thread)
スレッド内でインタラクションが発生した場合は、ユーザーがコマンドを使用したチャット スレッド。
chat.appCommandPayload.message object (Message)
ユーザーがスラッシュ コマンドとともに送信したメッセージ。
chat.appCommandPayload.configCompleteRedirectUri string
コマンドに認可または構成が必要な場合は、Google Chat の外部でプロセスを完了した後にユーザーをリダイレクトする URL。
chat.appCommandPayload.isDialogEvent boolean
コマンドでダイアログを開くかどうか。
chat.appCommandPayload.dialogEventType enum (DialogEventType)
ダイアログとのインタラクションのタイプ。

列挙型 DialogEventType。

dialogEventType の値は、次のいずれかの 1 つのみを指定できます。
TYPE_UNSPECIFIED デフォルト値。（指定なし）
REQUEST_DIALOG ユーザーがダイアログをリクエストします。たとえば、スラッシュ コマンドを使用するか、メッセージのボタンをクリックします。
SUBMIT_DIALOG ユーザーがダイアログ内のインタラクティブな要素をクリックします。たとえば、ユーザーがダイアログで情報を入力し、ボタンをクリックして情報を送信します。
アプリ コマンド メタデータ
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string (int64 format)

コマンド ID。
chat.appCommandPayload.appCommandMetadata.appCommandType enum (AppCommandType)
コマンドのタイプ。

列挙型 AppCommandType。

AppCommandType の値は、次のいずれかの 1 つのみを指定できます。
APP_COMMAND_TYPE_UNSPECIFIED デフォルト値。（指定なし）
SLASH_COMMAND ユーザーは、スラッシュ / で始まるメッセージを送信してコマンドを使用します。

チャットの操作

このセクションでは、Chat アプリでアドオン アクションを使用してユーザー操作に対応する方法について説明します。

アドオン アクションで応答するには、Chat アプリが 30 秒以内に応答し、インタラクションが発生したスペースにレスポンスを投稿する必要があります。それ以外の場合、Chat アプリは認証を設定し、Google Chat API を呼び出して応答する必要があります。

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

ユーザー操作に応答するには、Chat アプリは対応するイベント オブジェクトを処理し、次のいずれかの JSON オブジェクトを返す必要があります。

チャットアプリの望ましいレスポンス 返品に必要な対応
メッセージを送信または更新する。 DataActions
ダイアログを開く、更新する、閉じる。 RenderActions
カードまたはダイアログから情報を収集するには、ユーザーがマルチ選択メニューに入力した内容に基づいて選択項目を提案します。 RenderActions
Chat ユーザーがスペースで送信したメッセージ内のリンクをプレビューできます。 DataActions

Google Chat API を使用して返信する

Chat アプリでは、アドオン アクションを返す代わりに、Google Chat API を使用してインタラクションに応答する必要がある場合があります。たとえば、Chat アプリは、次のいずれかを行うために Google Chat API を呼び出す必要があります。

  • 30 秒後にインタラクションに応答します。
  • 操作が行われたスペースの外でタスクを実行する。
  • アドオン アクションとして利用できないタスクを Chat で実行します。たとえば、ユーザーまたは Chat アプリがメンバーであるスペースを一覧表示したり、スペースにユーザーを追加したりできます。
  • Chat ユーザーに代わってタスクを実行します（ユーザー認証が必要です）。

Chat API の認証と呼び出しについて詳しくは、Chat API の概要をご覧ください。