テキストとカードの使い分け

テキストメッセージは手軽だが、項目が5つを超えたあたりから読みにくくなる。カードメッセージは 見出し・ラベル付きの値・区切り線・ボタン を部品として並べられるので、通知を「書式の決まった報告書」にできる。

テキスト(text)カード(cardsV2)
向いている内容一言の通知、会話的な連絡、メンション結果の報告(状態・件数・所要時間)、複数の項目、リンク先がある通知
書式Chat の記法(*太字* など)HTML タグの一部(<b>、<font color> など)
ボタンなしリンクを開くボタンを置ける
作る手間少ないJSON が長くなるので、関数で部品化する(この記事の後半)

1つのメッセージに text と cardsV2 の両方を入れることもできる。メンションはテキスト側で行い、詳細はカードで見せる、という組み合わせが実務では使いやすい。

cardsV2 の構造

カードは「カード → セクション → ウィジェット」の3階層でできている。

夜間バッチ結果のカードの見た目と、cardsV2のheader・sections・widgetsの対応を示した図

図1: カードの見た目(左)と JSON の構造(右)

階層キー役割
カードの配列cardsV21メッセージに複数のカードを並べられる。各要素に cardId(任意の識別子)と card を持つ
ヘッダーcard.headertitle・subtitle・imageUrl(アイコン画像)。省略もできる
セクションcard.sections[]区切られたまとまり。header で小見出しを付けられる
ウィジェットsections[].widgets[]実際に表示される部品(次の表)

💡 古い cards ではなく cardsV2 を使う

ネット上の古い記事には "cards" というキーで書かれた例が残っているが、これは旧形式だ。新しく作るなら cardsV2 で書く。ウィジェットの名前や入れ子の形が違うので、古い例を混ぜて使うと 400 エラーになる。

最初のカードを送る

図1のカードを JSON で書くと次のようになる。PART 02 の post_message() にこの辞書を渡せば、そのまま送れる。

JSON(batch-card.json)
{
  "fallbackText": "夜間バッチ:成功(12,480件)",
  "cardsV2": [
    {
      "cardId": "batch-result",
      "card": {
        "header": {
          "title": "夜間バッチ結果",
          "subtitle": "2026-10-31 02:15 / prod"
        },
        "sections": [
          {
            "header": "サマリー",
            "widgets": [
              {
                "decoratedText": {
                  "topLabel": "ステータス",
                  "text": "<font color=\"#16a34a\"><b>成功</b></font>",
                  "startIcon": { "knownIcon": "STAR" }
                }
              },
              {
                "decoratedText": {
                  "topLabel": "処理件数",
                  "text": "12,480 件(所要 6分12秒)",
                  "startIcon": { "knownIcon": "DESCRIPTION" }
                }
              },
              { "divider": {} },
              {
                "textParagraph": { "text": "警告 2 件はログを確認してください。" }
              },
              {
                "buttonList": {
                  "buttons": [
                    { "text": "ログを開く", "onClick": { "openLink": { "url": "https://example.com/jobs/nightly/logs" } } },
                    { "text": "手順書",     "onClick": { "openLink": { "url": "https://example.com/runbook/nightly" } } }
                  ]
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
bash
curl -sS -X POST "$GCHAT_WEBHOOK_URL" \
  -H 'Content-Type: application/json; charset=UTF-8' \
  --data-binary @batch-card.json

fallbackText は、カードを表示できない場面(スマートフォンの通知など)で代わりに使われる短い説明だ。省略もできるが、通知のプレビューで内容がわかる ように入れておくことをおすすめする。

よく使うウィジェット

通知用途で使うウィジェットは、ほぼ次の表で足りる。

ウィジェット表示主なフィールド
decoratedTextラベル付きの値。アイコンや右端のボタンも付けられるtopLabel・text・bottomLabel・startIcon・wrapText
textParagraph文章のかたまりtext
buttonList横に並んだボタンbuttons[].text・buttons[].onClick.openLink.url
divider区切り線なし({})
image画像(グラフの PNG など)imageUrl・altText
columns2列のレイアウトcolumnItems[].widgets

値が長くて途中で切れる場合は、decoratedText に "wrapText": true を付けると折り返して表示される。項目が多いセクションは "collapsible": true と "uncollapsibleWidgetsCount": 3 を指定すると、最初の3つだけ見せて残りを「もっと見る」で開く形にできる。

アイコンは、knownIcon に組み込みの名前(STAR・DESCRIPTION・CLOCK・EMAIL・PERSON・MULTIPLE_PEOPLE・BOOKMARK など)を指定するのが手軽だ。Google の Material アイコンを使う場合は {"materialIcon": {"name": "check_circle"}} のように書く。

カード内で使える書式

カードの中のテキストは、テキストメッセージの記法ではなく HTML タグの一部 で装飾する。*太字* と書いてもカードの中では太字にならない。

表示タグ
太字・斜体・下線・取り消し線<b>・<i>・<u>・<s>
文字の色<font color="#dc2626">失敗</font>
リンク<a href="https://...">表示文字</a>
改行<br>

JSON の文字列の中に HTML を書くので、属性の " は \" とエスケープする。Python で辞書から json= で送れば、エスケープは自動で行われる。

⚠️ 色だけで状態を伝えない

赤・緑の色分けは見やすいが、ダークテーマや色の見分けにくい人には伝わりにくい。「成功」「失敗」の文字も必ず入れ、色は補助として使う。

Python でカードを部品化する

カードの JSON は長いので、毎回手で書くとすぐ間違える。よく使う形を関数にしておき、通知ごとには中身だけを渡すようにする。

Python(gchat_cards.py)
"""Google Chat の cardsV2 を組み立てる小さな部品集"""
from html import escape

STATUS_STYLE = {
    "success": ("成功", "#16a34a"),
    "warning": ("警告", "#d97706"),
    "failure": ("失敗", "#dc2626"),
}


def kv(label: str, value: str, icon: str | None = None) -> dict:
    """ラベル付きの値(decoratedText)"""
    w = {"topLabel": label, "text": escape(value), "wrapText": True}
    if icon:
        w["startIcon"] = {"knownIcon": icon}
    return {"decoratedText": w}


def paragraph(text: str) -> dict:
    return {"textParagraph": {"text": escape(text).replace("\n", "<br>")}}


def buttons(*links: tuple[str, str]) -> dict:
    """("表示文字", "URL") の組を受け取り、リンクを開くボタンを並べる"""
    return {"buttonList": {"buttons": [
        {"text": text, "onClick": {"openLink": {"url": url}}} for text, url in links
    ]}}


def status_card(title: str, subtitle: str, status: str, items: list[dict],
                note: str | None = None, links: list[tuple[str, str]] | None = None,
                card_id: str = "status") -> dict:
    """状態(success / warning / failure)付きの通知カードを、メッセージの辞書として返す"""
    label, color = STATUS_STYLE[status]
    widgets = [{"decoratedText": {
        "topLabel": "ステータス",
        "text": f'<font color="{color}"><b>{label}</b></font>',
    }}]
    widgets += items
    if note:
        widgets += [{"divider": {}}, paragraph(note)]
    if links:
        widgets.append(buttons(*links))
    return {
        "fallbackText": f"{title}:{label}",
        "cardsV2": [{
            "cardId": card_id,
            "card": {
                "header": {"title": title, "subtitle": subtitle},
                "sections": [{"widgets": widgets}],
            },
        }],
    }

値に < や & が含まれるとカードの HTML として解釈されてしまうので、html.escape() を通している。ログの一部やファイルパスを載せるときに効いてくる。

使う側は、通知したい項目を並べるだけになる。

Python(notify_batch.py)
from datetime import datetime

from gchat_cards import kv, status_card
from gchat_webhook import post_message

msg = status_card(
    title="夜間バッチ結果",
    subtitle=f"{datetime.now():%Y-%m-%d %H:%M} / prod",
    status="failure",
    items=[
        kv("ジョブ", "daily-aggregate", icon="DESCRIPTION"),
        kv("終了コード", "2"),
        kv("所要時間", "3分48秒", icon="CLOCK"),
    ],
    note="入力ファイル s3://example-bucket/in/2026-10-31.csv が見つかりませんでした。",
    links=[("ログを開く", "https://example.com/jobs/daily-aggregate/logs")],
)
# メンションはテキスト側で付ける(カードの中ではメンションできない)
msg["text"] = "<users/all> 夜間バッチが失敗しました"
post_message(msg, thread_key="batch-2026-10-31")

カードの見た目を試行錯誤するときは、Google の Card Builder が便利だ。部品を画面上で並べるとプレビューと JSON が表示されるので、それを見ながら関数を調整すると早い。

Webhook のカードでできないこと

カードには、押すと Chat アプリ側の処理を呼び出すボタンや、入力欄・選択肢などのウィジェットもある。しかし Webhook は送信専用で、ユーザーの操作を受け取る仕組みがないため、次のものは使えない(あるいは置いても意味がない)。

  • 押すと処理が動くボタン(onClick.action)――「再実行」「承認」ボタンなど
  • 入力欄・チェックボックス・選択肢(textInput・selectionInput など)
  • 送ったカードの後からの書き換え(「実行中」→「完了」の更新)

Webhook で置けるボタンは リンクを開く(openLink)ものだけ と考えておくとよい。「再実行」をボタン1つで済ませたい場合は、再実行用の URL(ジョブ管理画面や、認証付きの API の画面)を openLink で開かせるのが現実的だ。メッセージの書き換えは、PART 05 の Chat API でできるようになる。

つまずきやすい点

症状原因と対処
400 Unknown name "..."キー名の綴り違い、または旧形式(cards)の書き方が混ざっている。エラーに出たキー名を cardsV2 のリファレンスで確認する
画像が表示されないimageUrl がインターネットから見えない(社内サーバー、認証付きの S3 など)。公開されている HTTPS の URL が必要
カードの中で *太字* が効かないカードは HTML タグで装飾する。<b>太字</b> と書く
カードの中でメンションできないメンションはテキスト(text)側に書く
値の一部が消える・崩れる値に含まれる <・& が HTML として解釈されている。html.escape() を通す

✅ 次の記事では…

PART 04 では、ここまでの部品を「毎朝9時に送る」「アラームが鳴ったら送る」形に組み込む。Apps Script・Windows のタスクスケジューラ・AWS Lambda の3つの実行場所を扱う。

→ PART 04 — 定期投稿と自動化へ