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

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

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

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

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

他の 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'] オブジェクトには、ユーザーがメニューに入力した文字列値が含まれます。

ペイロード

インタラクションの種類に応じて、イベントには 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.addedToSpacePayload.interactionAdd boolean
メッセージを使用してユーザーが Chat アプリをスペースに追加したかどうか。たとえば、Chat アプリを @ メンションしたり、スラッシュ コマンドを使用したりします。true の場合、Chat は、メッセージに関する情報を含む messagePayload を含む別のイベント オブジェクトを送信します。

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

ボタンクリック ペイロード
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 スペース。

チャットの操作

このセクションでは、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 の概要をご覧ください。