目次
- Google Chat API・Webhook・Chatアプリの関係
- 用途別に何を選ぶか
- Webhook：固定スペースへの一方向通知
- Webhookが向くケース
- Chatアプリ：メッセージ・ボタン・ダイアログへ応答
- Google Chat APIでできること
- アプリ認証とユーザー認証の違い
- Apps Scriptは実行基盤として選ぶ
- メッセージ設計は通知文より先に決める
- スレッドと通知先を設計する
- エラー・クォータ・再送を前提にする
- セキュリティチェックリスト
- 導入手順
- 1. 通知か操作かを決める
- 2. 正本と元データIDを決める
- 3. 実行基盤を選ぶ
- 4. 認証・スペース・権限を設定する
- 5. 失敗と重複を試験する
- 6. 指標を見て運用する
- よくある失敗
- SakuraAIで支援できること
Google Chatの自動化は、特定スペースへの一方向通知ならWebhook、メンション・ボタン・ダイアログなど双方向処理ならChatアプリ、複数スペースやメンバーを操作するならChat APIを使います。Apps Scriptはこれらと並ぶ通知方式ではなく、Webhook送信やChatアプリを動かす実行基盤です。実装前に、通知か操作か、アプリ自身か利用者の代理かを決めると過剰開発を防げます。
本記事は2026年6月28日時点のGoogle公式情報をもとにしています。Chat APIの機能、OAuthスコープ、クォータ、WebhookやChatアプリの利用条件は変更される可能性があります。実装前に公式ドキュメントとGoogle Workspace管理者設定を確認してください。
Expert Q&A
Google Chat APIを使う前に確認すること
湯田英也SakuraAI株式会社 代表 / ソフトウェアエンジニアQ. 最初からChatアプリを作るべきですか？
A. 一方向通知だけならWebhookから始めます。問い合わせへの応答、承認ボタン、入力フォームが必要になった時点でChatアプリへ広げます。要件がないのに認証と実行環境を増やす必要はありません。
Q. Apps ScriptとChat APIはどちらを選びますか？
A. 比較するものではありません。Apps Scriptはコードを動かす場所、Chat APIはChatを操作するインターフェースです。Apps ScriptからChat APIを呼ぶ構成もあります。
Q. API連携で一番見落とされる点は？
A. 再送と重複です。タイムアウト後に再試行すると、同じ通知や承認処理が二度走ることがあります。元データIDと処理済みIDを持ち、何度呼ばれても結果が重複しないようにします。
Gmailの重要メールを担当スペースへ流す。フォーム回答を通知する。ボタンで承認する。社内FAQへ回答する。これらはすべてGoogle Chat連携ですが、必要な仕組みは同じではありません。
現行のGoogle公式ドキュメントでは、対話するBotはGoogle Chatアプリとして説明されています。また、Apps ScriptはWebhookやChat APIと競合する方式ではなく、コードを動かす選択肢の一つです。この違いを混同したまま作り始めると、通知したいだけなのに認証まわりで沼にはまる、という遠回りになりがちなので、まず用語と役割から整理します。
Google Chat API・Webhook・Chatアプリの関係
| 仕組み | 主な役割 | 受信・操作 | 認証 | 向く用途 |
|---|---|---|---|---|
| 受信Webhook | 登録したスペースへ投稿 | 送信のみ。ユーザー操作は受け取れない | 秘密のWebhook URL | 監視通知、定期レポート、簡易連携 |
| Chatアプリ | Chat内で対話・操作 | メッセージ、コマンド、カード、ダイアログへ応答 | 構成と用途に応じてアプリ・ユーザー認証 | FAQ、申請、承認、業務Bot |
| Chat API | Chatリソースをプログラム操作 | メッセージ、スペース、メンバーなど | OAuth 2.0 / サービスアカウント | 動的な通知先、スペース管理、システム連携 |
| Apps Script | Google環境でコードを実行 | Webhook送信、API呼び出し、イベント処理 | Googleが実行認可を管理 | Gmail・Forms・Sheets起点の小規模連携 |
| 外部実行環境 | API処理と業務ロジックを実行 | Chatと外部システムを接続 | Cloud IAM、OAuthなど | 高可用性、複雑な連携、詳細な監視 |
WebhookでもChat APIのメッセージ作成エンドポイントへPOSTしますが、用途と認証が簡略化されています。Webhookは登録したスペース専用で、ユーザーからの返信やクリックを受け取れません。この表の一番のポイントは、機能の多さで選ばないこと。要件がどこまでなら、どこで止めるかを先に決めるのが、過剰開発を避ける近道です。
用途別に何を選ぶか
Decision chart
Google Chat連携の実装開始点
要件の単純さ、実装量、運用負荷、誤操作時の影響をもとにSakuraAIが整理した初期選択スコアです。Google公式の評価ではありません。
一方向で通知先が固定なら最小構成
Googleイベント起点の小規模連携に向く
通知先・認証・メンバーシップの設計が必要
カード、ボタン、ダイアログの処理が必要
権限、根拠、有人引き継ぎまで設計する
管理権限、監査、失敗時の影響が大きい
通知だけの要件にChatアプリを作ると、認証、公開範囲、受信エンドポイント、イベント処理の運用が増えます。反対に、Webhookで承認を作ろうとしても、ユーザー操作を受信できません。
Webhook：固定スペースへの一方向通知
受信Webhookは、外部サービスからGoogle Chatスペースへ非同期の一方向通知を送る仕組みです。ユーザーはWebhookへ話しかけたり、接続先の処理をボタンで呼び出したりできません。
最小の送信例は次の通りです。
curl -X POST "$GOOGLE_CHAT_WEBHOOK_URL" \
-H "Content-Type: application/json; charset=UTF-8" \
-d '{"text":"[INFO] 日次処理が完了しました"}'
Webhook URLには key と token が含まれます。コードへ直書きせず、環境変数やシークレット管理へ置きます。URLが漏れた場合は、該当Webhookを作り直して送信元の設定を更新します。
Webhook URLをマスキングせずログへ出力しないでください。URLを知る相手は、そのスペースへ投稿できる可能性があります。公開リポジトリ、エラーメール、Chat本文にも貼らないようにします。
Webhookが向くケース
- 監視アラートや障害通知
- バッチ、バックアップ、デプロイの結果
- Googleフォームの新規回答
- Gmailの特定ラベルへの受信通知
- 日次・週次の集計レポート
Webhookは threadKey を使ったスレッドへの投稿にも対応します。同じ案件やアラートをスレッドへまとめると、スペースの流量を抑えられます。
Chatアプリ：メッセージ・ボタン・ダイアログへ応答
Chatアプリは、ユーザーのメッセージ、メンション、コマンド、カードのボタン、ダイアログ送信などをインタラクションイベントとして受け取ります。
| 入力 | Chatアプリの応答例 | 実務用途 |
|---|---|---|
| メッセージ・メンション | 質問へ回答、分類、担当通知 | 社内FAQ、問い合わせ受付 |
| コマンド | 決まった処理を起動 | レポート取得、申請開始 |
| カードのボタン | 状態更新、確認画面を開く | 承認、担当引受、解決確認 |
| ダイアログ | 構造化された入力を受け付ける | 申請、問い合わせ、差戻し理由 |
| アプリホーム | 利用者ごとの一覧や入口を表示 | 未処理タスク、ヘルプメニュー |
Webhookでも表示用のカードを送れますが、接続先アプリへ操作を返す会話型の処理はできません。クリック後に状態を変える場合はChatアプリとしてイベントを受け取ります。
Google Chat APIでできること
Chat APIは、認証されたアプリやユーザーからGoogle Chatのリソースを操作します。代表的な用途は次の通りです。
| 対象 | 主な操作 | 用途例 |
|---|---|---|
| メッセージ | 作成、取得、更新、削除 | 通知、カード更新、状態表示 |
| スペース | 作成、取得、更新、検索 | 案件・障害対応スペースの準備 |
| メンバー | 追加、取得、削除 | プロジェクト参加者の管理 |
| リアクション | 作成、一覧、削除 | 簡易な確認状態の取得 |
| 添付 | アップロード、取得 | Chatアプリのファイル連携 |
| イベント | 購読、取得 | メッセージやメンバー変更への応答 |
すべての操作が同じ認証方式で使えるわけではありません。APIメソッドごとに、アプリ認証、ユーザー認証、管理者権限、必要なスコープを公式リファレンスで確認します。
アプリ認証とユーザー認証の違い
| 観点 | アプリ認証 | ユーザー認証 |
|---|---|---|
| 主体 | Chatアプリ自身 | OAuthで認可した利用者 |
| 主な資格情報 | サービスアカウント | OAuth 2.0アクセストークン |
| 見える範囲 | アプリのメンバーシップと権限の範囲 | 利用者が持つ権限の範囲 |
| 向く用途 | Bot投稿、アプリとしてのスペース操作 | 利用者代理の作成・管理、他Workspace API連携 |
| 注意点 | 秘密鍵、管理者承認が必要なスコープ | 同意画面、トークン、利用者ごとの権限 |
ユーザー認証を使えば、その利用者の代理でスペース作成やGmail・Calendarなど他のWorkspace API操作もできます。一方、必要以上に広い権限を要求すると、情報漏えい時の影響も大きくなります。
ドメイン全体の委任は、利用者ごとの同意を省く便利機能ではありません。管理者権限でユーザーデータへアクセスできるため、対象業務、スコープ、監査、資格情報の管理を厳しく設計します。
Apps Scriptは実行基盤として選ぶ
Apps Scriptには主に3つの使い方があります。
- Gmail、Forms、Sheets、CalendarなどのイベントからWebhookへPOSTする
- 高度なChatサービスやHTTP経由でChat APIを呼ぶ
- Chatアプリのイベントを受けて応答する
| 実行基盤 | 強み | 弱み | 向く規模 |
|---|---|---|---|
| Apps Script | Workspace連携が早く、サーバー管理が少ない | 実行時間、クォータ、監視、デプロイ管理に制約 | 小規模な社内自動化 |
| Cloud Run / Functionsなど | スケール、監視、ネットワーク、デプロイを管理しやすい | Cloud構成と運用が必要 | 外部連携、複雑なChatアプリ |
| 既存業務システム | 元データと処理を同じ場所で管理できる | Chat認証とAPI実装が必要 | 既存サービスからの通知・操作 |
| ノーコード・ワークフロー | 単純な連携を短時間で作れる | 複雑な例外、監査、独自認証に限界 | 定型通知と簡易承認 |
Apps Scriptで始め、処理量や監視要件が上がったら外部実行環境へ移す方法もあります。最初から将来の全機能を見込んで大きく作る必要はありません。
メッセージ設計は通知文より先に決める
| 要素 | 含める内容 | 理由 |
|---|---|---|
| 種別・重要度 | 障害、申請、問い合わせ、定期報告など | 読む優先順位を判断できる |
| 対象ID | 案件ID、申請ID、アラートID | 重複防止と追跡に使える |
| 要点 | 何が起きたか | 全文を開かず概要を把握できる |
| 担当者 | 次に対応する人 | 通知だけで放置されない |
| 期限・状態 | いつまでに何をするか | 次アクションを明確にする |
| 正本リンク | 元システムやDriveのURL | Chatを正本にしない |
| 操作 | 開く、担当する、差戻すなど | 文章返信による表記揺れを減らす |
Chatにデータ全文を複製せず、判断に必要な要点と正本リンクを載せます。機密情報、個人情報、認証情報は、スペースのメンバーと履歴設定も考慮して絞ります。
スレッドと通知先を設計する
| 設計 | 向く内容 | 注意点 |
|---|---|---|
| 1イベント1投稿 | 単発の申請・問い合わせ | 件数が多いとスペースが流れる |
| 1案件1スレッド | 障害、案件、問い合わせの継続更新 | 一貫した threadKey を持たせる |
| 日次集約投稿 | 件数・ステータスの定期報告 | 緊急事象を集約待ちにしない |
| 担当スペース分割 | 部門や業務ごとの通知 | スペース乱立とメンバー管理に注意 |
| DM通知 | 個人だけが対応する情報 | チームから進捗が見えなくなる |
すべてを1つのスペースへ流すより、誰が行動する通知かで分けます。個人へのDMだけで完結すると引き継げないため、正本側に担当と状態を残します。
エラー・クォータ・再送を前提にする
Google公式ドキュメントでは、Chat APIの時間ベースの制限超過時に 429 が返り、指数バックオフで再試行するよう案内されています。2026年6月28日時点では、同一スペースへの書き込みは原則1秒あたり1回の制限があります。
複数の通知元が同じスペースへ集中する場合は、送信キューで順番を制御します。リトライは無限に続けず、回数上限と失敗通知を持たせます。
| 失敗 | 対応 |
|---|---|
400系の不正リクエスト | 自動再試行せず、ペイロードとコードを確認 |
401・403 | 認証情報、スコープ、メンバーシップを確認 |
404 | スペース、メッセージ、Webhookの削除を確認 |
429 | 指数バックオフし、送信量を制御 |
500系・ネットワーク | 上限つきで再試行し、失敗キューへ保存 |
| タイムアウト | 成功済みの可能性を考え、元データIDで重複防止 |
Chatアプリへのインタラクションイベントも、通信状況により同じイベントが複数回届く可能性があります。承認や状態更新では、操作IDを保存し、処理済みなら同じ結果を返します。
処理が長い場合は、同期応答の中で全部を終わらせず、受付を返して非同期処理後にChat APIで結果を投稿します。
セキュリティチェックリスト
| 確認項目 | 対策 |
|---|---|
| Webhook URL | シークレット管理、ログ除外、漏えい時の再発行 |
| サービスアカウント | 必要最小権限、秘密鍵の安全な保管、定期見直し |
| OAuthスコープ | 機能に必要な範囲だけ要求 |
| Chatスペース | メンバー、外部参加、履歴、投稿対象を確認 |
| イベント入力 | 操作者、対象ID、許可された状態遷移を検証 |
| ログ | 本文や秘密情報を不要に記録しない |
| 管理者権限 | 利用目的、承認、監査、失効手順を明確にする |
| 障害対応 | 停止方法、再処理、通知先、担当者を決める |
導入手順
1. 通知か操作かを決める
ユーザー入力を受けない固定スペースへの通知ならWebhook、メンションやボタンを受けるならChatアプリです。複数スペースやメンバー操作が必要ならChat APIの認証を設計します。
2. 正本と元データIDを決める
Chat投稿を正本にせず、元システムのIDとリンクを持たせます。通知、再送、更新、削除を同じIDで追跡します。
3. 実行基盤を選ぶ
GmailやForms起点の小規模連携はApps Script、外部サービスや詳細監視が必要なら既存システムやCloud実行環境を選びます。
4. 認証・スペース・権限を設定する
アプリ認証とユーザー認証を使い分け、スコープとメンバーシップを最小化します。テスト用スペースとテストユーザーで検証します。
5. 失敗と重複を試験する
ネットワーク失敗、429、削除済みWebhook、権限不足、同一イベント再送を意図的に確認します。成功ケースだけで本番へ出しません。
6. 指標を見て運用する
| 評価項目 | 見る内容 |
|---|---|
| 配信成功率 | 正常にChatへ届いた割合 |
| 通知遅延 | 元イベントから投稿までの時間 |
| 重複投稿 | 同じ元データIDで複数投稿された件数 |
| 再試行・失敗 | HTTPコード別の件数と最終結果 |
| 未対応 | 通知後も担当・状態が更新されない件数 |
| 操作エラー | 権限不足、無効な状態遷移、二重操作 |
| 通知量 | スペース・種別ごとの投稿件数 |
よくある失敗
| 失敗 | 起きること | 回避策 |
|---|---|---|
| Apps ScriptとWebhookを同列比較する | 実行場所と通知方式が混ざる | 要件、方式、実行基盤を分ける |
| 通知だけなのにChatアプリを作る | 認証と運用が過剰になる | Webhookから始める |
| Webhookで承認を作ろうとする | ユーザー操作を受け取れない | Chatアプリでイベント処理する |
| Webhook URLをコードへ書く | 漏えい時に第三者が投稿できる | シークレット管理へ置く |
| 失敗時に即時連続リトライする | クォータ超過を悪化させる | 指数バックオフと上限を設ける |
| タイムアウト後に無条件再送する | 通知・承認が重複する | 元データIDと操作IDで冪等化する |
| Chatを正本にする | 更新・監査・検索が難しくなる | 元システムへ状態と履歴を残す |
SakuraAIで支援できること
SakuraAIは、Google Chat APIを使うこと自体を目的にせず、Webhookで足りる通知、Chatアプリが必要な操作、Apps Scriptで動かせる処理、外部実行環境が必要な連携を切り分けます。
認証、カード・ダイアログ、スレッド、メッセージ設計、再送・重複防止、クォータ、監視、運用停止まで含めて実装します。小さな通知から始め、必要な機能だけ段階的に広げます。
Expert Q&A
最後に湯田へ確認
湯田英也SakuraAI株式会社 代表 / ソフトウェアエンジニアQ. WebhookからChatアプリへ移る目安は？
A. ユーザーの入力や操作を受け取りたくなったときです。メンション応答、担当引受、承認、差戻し、入力フォームが必要ならChatアプリを検討します。通知先が増えただけならChat APIでの送信も比較します。
Q. 実装が成功した状態とは？
A. 通知が届くだけでなく、重複せず、担当者が次の行動を取れ、失敗時に再処理できる状態です。送信件数ではなく、未対応、遅延、エラー、重複を測ります。
Q. 本番前に最低限試すことは？
A. 権限不足、削除済みスペース、429、ネットワーク失敗、同じイベントの再送です。承認系では、同じボタンが二度処理されないことと、権限のない人が操作できないことも確認します。
よくある質問
Google Chat APIとWebhookはどう違いますか？
Google Chat APIはメッセージ、スペース、メンバーなどを操作する公式APIです。受信Webhookは、登録した1つのスペースへ一方向に通知する簡易な仕組みで、ユーザーのメッセージやボタンクリックを受け取れません。通知だけならWebhook、対話や動的な操作が必要ならChatアプリを使います。
BotとChatアプリは同じものですか？
以前Botと呼ばれていたものを含め、Googleの現行ドキュメントではChatアプリという表現が中心です。メンション、コマンド、カード、ダイアログへ応答する双方向の仕組みを指します。
Apps ScriptだけでGoogle Chat連携できますか？
できます。ただしApps Scriptは通知方式ではなく実行基盤です。Apps ScriptからWebhookへPOSTする、Chat APIを呼ぶ、Chatアプリの受信処理を動かすなど複数の使い方があります。
アプリ認証とユーザー認証はどう使い分けますか？
アプリ認証はサービスアカウントなどを使い、Chatアプリ自身として処理します。ユーザー認証はOAuth 2.0で利用者の権限を使い、その人の代理でスペース作成や他のWorkspace API操作を行います。必要な機能から最小権限を選びます。
Webhook URLを漏らした場合はどうすればよいですか？
Webhook URLには秘密のキーとトークンが含まれます。該当Webhookを無効化・再作成し、シークレット管理の値を更新します。コード、ログ、Chat本文、公開リポジトリへURLを残さないでください。
参考・一次情報
開発相談
Google Chat Bot・Webhook開発を相談する
通知・承認・問い合わせ連携のBotとAPI実装を支援します。
開発を相談する