Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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

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

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

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

Chat 用アプリがスペースに追加されたトリガーからイベントオブジェクトを受け取る — **図 1**: ユーザーが Chat 用アプリをスペースに追加すると、**スペースに追加**トリガーが起動し、イベントオブジェクトが送信されます。メッセージで応答するには、Chat 用アプリがイベントオブジェクトを処理し、メッセージを作成するアクションを返します。

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

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

トリガー

このセクションでは、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 用アプリのコマンドを使用する。	Chat 用アプリがコマンドに応答します。たとえば、メッセージで返信したり、ダイアログを開いたりします。
アプリのホーム画面	ユーザーが Chat 用アプリとの 1 対 1 のダイレクトメッセージ（DM）スペースで [ホーム] タブを開くか、ホームページカードのウィジェットを操作します。	Chat 用アプリは、ホームページカード（`pushCard`）をプッシュするか、表示されているホームページカード（`updateCard`）を更新する `RenderActions` オブジェクトを返します。

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

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

イベントオブジェクト

Chat アプリは、Chat トリガーが実行されたとき、または Chat ユーザーが Chat 用アプリの UI（ボタンのクリックなど）を操作したときに、イベントオブジェクトを受け取ります。イベントオブジェクトを使用すると、インタラクションデータを使用して UI を応答または更新できます。

イベントオブジェクトのペイロード

各 Chat イベントオブジェクトには、ホストとプラットフォームの詳細（hostApp: "CHAT"、clientPlatform、userLocale、userTimezone、formInputs）を含む commonEventObject と、Chat 固有のコンテキストを含む chat オブジェクトが含まれます。

アプリホーム トリガー（ユーザーが Chat 用アプリとの 1 対 1 のダイレクトメッセージで [ホーム] タブを開いた場合）の場合、chat オブジェクトには、共用体 payload フィールドなしで chat.user と chat.eventTime が含まれます。ユーザーがホームページカードのボタンをクリックすると、イベントオブジェクトには commonEventObject.parameters（カードにフォーム入力が含まれている場合は commonEventObject.formInputs も）が含まれます。
スペースとメッセージのインタラクション（スペースに追加、メッセージ、スペースから削除、アプリコマンド、ボタンとウィジェットのインタラクション）の場合、chat オブジェクトには chat.user、chat.space、chat.eventTime、対応するインタラクションペイロード（messagePayload、addedToSpacePayload、removedFromSpacePayload、buttonClickedPayload、widgetUpdatedPayload、appCommandPayload）が含まれます。

イベントオブジェクトの処理については、次のガイドをご覧ください。

Chat や他の Google Workspace アプリケーション内のアドオンイベントオブジェクトについては、イベントオブジェクトをご覧ください。

チャットの操作

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

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

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

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

DataActions: Google Workspace データの作成または更新を行います。Chat メッセージを送信または更新するには、オブジェクトに Message データの変更を定義するマークアップが含まれている必要があります。これは chatDataActionMarkup として表されます。
RenderActions: ホームページまたはダイアログを作成または更新するか、複数選択メニューの入力候補を提供します。
AuthorizationError: 認証カードを使用して、Google 外部のサービスにログインまたは認証するようユーザーに促します。Chat では、基本的な認証カードのみがサポートされています。

次の表に、Chat 用アプリがアクションで応答する方法を示します。Chat 用アプリは、JSON オブジェクトを返すか、Apps Script の AddOnResponseService を使用してレスポンスを作成できます。

Chat アプリの応答	返す必要があるアクション（JSON）	戻り値に必要なアクション（Apps Script）
メッセージを送信または更新する。	`DataActions`	`DataActionsResponse`
ダイレクトメッセージの [ホーム] タブでホームページをレンダリングまたは更新します。	`RenderActions`	`ActionResponse`
ダイアログを開く、更新する、閉じる。	`RenderActions`	`ActionResponse`
カードまたはダイアログから情報を収集するには、ユーザーが複数選択メニューに入力した内容に基づいて選択項目を提案します。	`RenderActions`	`ActionResponse`
Chat ユーザーがスペースで送信したメッセージ内のリンクのプレビュー。	`DataActions`	`DataActionsResponse`

Google Chat API を使用して応答する

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

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

30 秒後にインタラクションイベントに応答する場合は、Chat 用アプリが応答していないというユーザー向けのエラーメッセージが表示されないように、次の例に示すように、30 秒以内に空のレスポンスを送信してインタラクションイベントの受信を確認する必要があります。

Node.js

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

Python

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  # Respond with an empty response to the Google Chat platform.
  return {}

Java

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

Apps Script

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

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