Chat API が必要になる場面

PART 04 までの通知は、すべて Webhook で作れた。Chat API に移る理由がなければ、Webhook のままで十分だ。移る価値があるのは、次のどれかが必要になったときである。

やりたいことWebhookChat API
「実行中」と送ったメッセージを「完了」に書き換えるできないspaces.messages.patch
誤って送ったメッセージを消すできない(手で消す)spaces.messages.delete
同じアプリとして複数のスペースに送るスペースごとに URL を管理アプリを追加したスペースならどこでも
スペースやメンバーの一覧を取る(メンション用のユーザー ID など)できないspaces.list / spaces.members.list
組織のポリシーで Webhook が禁止されている使えないChat アプリが許可されていれば使える

この回では、Chat アプリを作ってサービスアカウントで認証し(アプリ認証)、投稿・書き換え・削除までを行う。ユーザー本人として投稿する「ユーザー認証」もあるが、通知用途では「誰が送ったか」がアプリ名で明確になるアプリ認証のほうが向いている。

Google Cloud 側の準備

Google CloudプロジェクトでChat APIを構成しサービスアカウントを作成、スペースにアプリを追加してスクリプトから投稿と書き換えを行う流れ

図1: Chat API で投稿するまでの準備(①〜④)と、メッセージの書き換え

Chat アプリは 1つの Google Cloud プロジェクトに1つ 作る。通知専用のプロジェクト(例:gchat-notify)を新しく作っておくと、権限や鍵の管理が他と混ざらない。手順は Workspace のアカウントで Google Cloud コンソールにログインして行う。

1. プロジェクトを作り、Google Chat API を有効にする

  1. Google Cloud コンソールで新しいプロジェクトを作る(組織は自社の Workspace を選ぶ)
  2. API とサービス → ライブラリ で「Google Chat API」を検索し、有効にする
  3. OAuth の同意画面(Google Auth Platform)の設定を求められたら、ユーザーの種類を 内部 にし、アプリ名とサポートのメールアドレスだけ入れて保存する

2. Chat API の「構成」でアプリを作る

Google Chat API のページの 構成 タブが、Chat 上に表示される「アプリ」の設定画面になる。

項目設定する値
アプリ名Chat に表示される名前(25文字まで)。例:運用通知
アバターの URL正方形の PNG / JPEG の HTTPS URL(256×256 ピクセル以上を推奨)
説明40文字まで。例:バッチ・アラームの結果を通知します
マークアップ構文テキストの書式(後述)。Webhook 用に書いたメッセージを流用するなら「Chat」
インタラクティブ機能有効にする。機能で「スペースとグループの会話に参加する」を選ぶ
接続設定HTTP エンドポイント URL など(後述)
公開設定このアプリを使えるようにするユーザー。最初は自分のメールアドレス、運用時はチームの Google グループを指定する
ログ「エラーを Logging に記録」にチェックしておくと、原因調査が楽になる

画面に「Google Workspace アドオンとしてこの Chat 用アプリを作成する」といったチェックボックスが表示される場合、この記事の手順は従来型の Chat アプリを前提にしているので、チェックを外して進める。

接続設定(イベントの送り先)について

インタラクティブ機能を有効にすると、接続設定(ユーザーがアプリにメンションしたときなどにイベントを届ける先)の入力を求められる。インタラクティブ機能を無効にしたままだと、Chat の画面からアプリを検索してスペースに追加できないため、通知専用のアプリでもここは埋める必要がある。

通知専用で応答を作らないなら、自分たちが管理する HTTPS の URL を入れておけばよい。届いたイベントに応答しない場合、ユーザーがアプリにメンションすると「応答がありません」と表示されるが、API からの投稿には影響しない。後で対話型にしたくなったら、ここを Cloud Run や Apps Script のデプロイに差し替える。

3. サービスアカウントとキーを作る

  1. IAM と管理 → サービス アカウント → サービス アカウントを作成 で、名前(例:gchat-notifier)を付けて作る。プロジェクトのロールは付けなくてよい
  2. 作成したサービスアカウントを開き、キー → 鍵を追加 → 新しい鍵を作成 → JSON で鍵ファイルをダウンロードする

スコープ https://www.googleapis.com/auth/chat.bot を使うアプリ認証は、Workspace の管理者による承認がいらない。サービスアカウントは「このアプリとして API を呼ぶための身分証」で、Chat 上の名前やアイコンは手順2の構成のものが使われる。

⚠️ 鍵ファイルの作成が禁止されている組織がある

サービスアカウントの鍵は漏れると悪用されやすいため、新しく作られた Google Cloud の組織では、組織ポリシーで鍵の作成が既定で禁止されていることがある。「鍵を追加」でエラーになったら、組織の管理者に例外を相談するか、Google Cloud の中(Cloud Run など)で、サービスアカウントを直接割り当てて動かす方法を検討する。鍵の扱いは PART 06 でも触れる。

スペースにアプリを追加し、スペース名を調べる

アプリ認証では、アプリがメンバーになっているスペースにしか投稿できない。投稿先のスペースで、次の操作をする。

  1. スペース名の横の下向き矢印 → アプリとインテグレーション を開く
  2. アプリを追加 をクリックし、手順2で付けたアプリ名を検索して追加する

次に、API で指定する スペース名(spaces/AAAA... の形)を調べる。ブラウザで Chat のスペースを開いたときの URL の末尾の ID がそれにあたる。

スペースの URL とスペース名の対応
https://mail.google.com/chat/u/0/#chat/space/AAAAxxxxxxx
                                              ↓
スペース名 = spaces/AAAAxxxxxxx

同じスペースに Webhook がある場合は、Webhook URL の spaces/AAAAxxxxxxx の部分も同じ値だ。アプリが参加しているスペースの一覧は、後述 の spaces.list でも取得できる。

Python で投稿する

PowerShell / bash
pip install google-api-python-client google-auth

鍵ファイルのパスとスペース名は環境変数から読む。クライアントを作る処理をモジュールにしておくと、以降の例で使い回せる。

Python(gchat_api.py)
"""Google Chat API をアプリ認証(サービスアカウント)で呼ぶための小さなモジュール"""
import os

from google.oauth2 import service_account
from googleapiclient.discovery import build

SCOPES = ["https://www.googleapis.com/auth/chat.bot"]
SPACE = os.environ["GCHAT_SPACE"]  # 例: spaces/AAAAxxxxxxx


def chat_client():
    creds = service_account.Credentials.from_service_account_file(
        os.environ["GCHAT_SA_KEY"], scopes=SCOPES   # 鍵ファイル(JSON)のパス
    )
    return build("chat", "v1", credentials=creds, cache_discovery=False)


def create_message(body: dict, message_id: str | None = None,
                   thread_key: str | None = None, space: str = SPACE) -> dict:
    params = {"parent": space, "body": body}
    if message_id:
        params["messageId"] = message_id  # 後から書き換えるための自分で決めた ID
    if thread_key:
        params["body"] = {**body, "thread": {"threadKey": thread_key}}
        params["messageReplyOption"] = "REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
    return chat_client().spaces().messages().create(**params).execute()


if __name__ == "__main__":
    print(create_message({"text": "Chat API からのテスト投稿です。"}))
PowerShell
$env:GCHAT_SA_KEY = 'C:\secure\gchat-notifier.json'
$env:GCHAT_SPACE  = 'spaces/AAAAxxxxxxx'
python gchat_api.py

Webhook と違い、応答にはメッセージ全体(送信者・作成日時・本文など)が返る。sender を見ると、送信者がアプリ("type": "BOT")になっていることを確認できる。メッセージの JSON(text・cardsV2・thread)は Webhook とまったく同じなので、PART 03 の status_card() もそのまま create_message() に渡せる。

メッセージを書き換える・削除する

Chat API ならではの使い方が、1つのメッセージを状況に合わせて書き換える ことだ。たとえば長いバッチの開始時に「⏳ 実行中」と投稿しておき、終わったら同じメッセージを「✅ 完了(所要時間)」に書き換える。スペースに流れるメッセージは1つのままで、見る人は最新の状態だけを読めばよい。

書き換えるには、対象のメッセージの名前(spaces/.../messages/...)が必要になる。投稿時の応答から取ってもよいが、投稿するときに自分で messageId を決めておく と、別のプロセスからでも同じ名前で書き換えられて便利だ。messageId は client- で始め、英小文字・数字・ハイフンだけで63文字以内にする。

Python(progress.py)
import time
from datetime import date

from gchat_api import SPACE, chat_client, create_message

job = "daily-aggregate"
message_id = f"client-{job}-{date.today():%Y%m%d}"   # 例: client-daily-aggregate-20261031
name = f"{SPACE}/messages/{message_id}"

# 1. 開始時に投稿
create_message({"text": f"⏳ *{job}* 実行中…"}, message_id=message_id)

started = time.monotonic()
# ... 長い処理 ...
elapsed = int(time.monotonic() - started)

# 2. 終了時に同じメッセージを書き換える(updateMask で変える項目を指定)
chat_client().spaces().messages().patch(
    name=name,
    updateMask="text",
    body={"text": f"✅ *{job}* 完了({elapsed // 60}分{elapsed % 60}秒)"},
).execute()

カードを書き換えるときは、updateMask に cards_v2 を指定し、body に新しい cardsV2 を入れる(テキストとカードの両方なら text,cards_v2)。書き換えでは、新しい投稿のようにメンバーへ改めて通知が飛ぶことは通常ないので、「開始」と「完了」で2回通知されるのを避けたい場面にも向いている。

削除は名前を指定するだけだ。

Python
chat_client().spaces().messages().delete(name=name).execute()

💡 アプリが書き換え・削除できるのは自分が送ったメッセージだけ

アプリ認証では、そのアプリ自身が作成したメッセージしか更新・削除できない。人が書いたメッセージや、Webhook が送ったメッセージは対象外だ。

スペースとメンバーの一覧を取る

アプリが参加しているスペースの一覧と、スペースのメンバー一覧は次のように取れる。複数のスペースに同じ通知を送る、メンション用のユーザー ID を調べる、といった用途に使う。

Python(list_spaces.py)
from gchat_api import chat_client

chat = chat_client()

# アプリが参加しているスペース
for space in chat.spaces().list().execute().get("spaces", []):
    print(space["name"], space.get("spaceType"), space.get("displayName", ""))

# あるスペースのメンバー(users/数字 がメンションに使うユーザー ID)
resp = chat.spaces().members().list(parent="spaces/AAAAxxxxxxx").execute()
for m in resp.get("memberships", []):
    member = m.get("member", {})
    print(member.get("name"), member.get("type"), member.get("displayName", ""))

結果が多いときは、応答の nextPageToken を次の呼び出しの pageToken に渡して続きを取る(考え方は boto3 のページネーション と同じ)。アプリ認証では、メンバーの表示名など一部の項目が返らないことがあるので、名前とユーザー ID の対応表を作るときは、Chat の画面と見比べて確認したい。

書式の違い:Markdown と Chat 記法

Webhook から移ってきたときに一番つまずくのが、テキストの書式だ。Webhook の既定は Chat 独自の記法 だが、新しく作った Chat アプリの既定は標準の Markdown になっている。

表示Chat 記法(Webhook の既定)Markdown(新しい Chat アプリの既定)
太字*太字***太字**
斜体_斜体_*斜体*
取り消し線~取り消し~~~取り消し~~
リンク<URL|表示文字>[表示文字](URL)
メンション<users/123...><chat-user data-user="users/123...">

表のとおり、Chat 記法の *太字* は Markdown では 斜体 として表示されてしまう。Webhook 用に書いたメッセージをそのまま Chat API に流すなら、構成画面の マークアップ構文 を「Chat」に切り替えておくのが簡単だ。新しく書くなら Markdown にそろえてもよいが、Webhook と Chat API が混在している間は、どちらか一方に統一しておくことをおすすめする。カードの中の書式(HTML タグ)はどちらの設定でも変わらない。

つまずきやすい点

症状原因と対処
スペースの「アプリを追加」でアプリが見つからない構成の 公開設定 に自分(またはグループ)が入っていない、インタラクティブ機能が無効、構成を保存していない
403 / 404 でスペースに投稿できないアプリがそのスペースのメンバーになっていない、またはスペース名の誤り(spaces/ の付け忘れなど)
投稿時に Google Chat app not found のようなエラーChat API は有効にしたが「構成」を保存していない。構成タブでアプリ名などを入れて保存する
書き換えで 404messageId が違う、または別のアプリ・Webhook が送ったメッセージを指定している
400 で messageId が不正と言われるclient- で始まっていない、大文字や _ を含んでいる、63文字を超えている
*太字* が斜体になるアプリのマークアップ構文が Markdown。上記 のとおり「Chat」に切り替えるか、**太字** で書く

✅ 次の記事では…

最終回の PART 06 では、Webhook URL とサービスアカウントの鍵の守り方、429 に備えたリトライ、長文の分割、よくあるエラーの一覧、そして「通知が多すぎて読まれない」を防ぐ設計をまとめる。

→ PART 06 — 運用とトラブルシューティングへ